passthru

PASSTHRU.SYS - Sample NDIS Intermediate Driver

SUMMARY

Passthru Intermediate Miniport Driver

The Passthru sample is a do-nothing pass-through NDIS 5 driver that demonstrates the basic principles underlying an NDIS Intermediate Miniport (IM) driver. This driver exposes a virtual adapter for each binding to a real or virtual NDIS adapter. Protocols bind to these virtual adapters as if they are real adapters.

The Passthru driver re-packages and sends down all requests and sends submitted to this virtual adapter. The Passthru driver can be modified to change the data before passing it along. For example, it could encrypt/compress outgoing and decrypt/decompress incoming data.

Passthru also re-packages and indicates up all received data and status indications that it receives at its lower (protocol) edge.

A related sample is the PASSTHRU notification object sample found under network\ndis\Passthru\notifyob in this DDK.

BUILDING THE SAMPLE

Run the build command from this directory to build the sample—it creates the binary Passthru.sys.

To install this driver on Windows® 2000, use the PASSTHRU sample notification object and INFs, also found in this DDK.

INSTALLING THE SAMPLE

Passthru is installed as a service (called “Passthru Driver” in the supplied INFs/notification object). To install, follow the steps below.

Prepare a floppy disk (or installation directory) that contains these files: netsf.inf, netsf_m.inf, passthru.sys and passthru.dll (notification object DLL, built in this DDK at network\ndis\Passthru\notifyob).

On the desktop, right-click the My Network Places icon and choose Properties.

Right-click on the relevant Local Area Connection icon and choose Properties.

Click Install, then Service, then Add, then Have Disk.

Browse to the drive/directory containing the files listed above. Click OK. This should show “Passthru Driver” in a list of Network Services. Highlight this and click OK. This should install the Passthru driver.

Click OK or Yes each time the system prompts with a warning regarding installation of unsigned files. This is necessary because binaries generated via the DDK build environment are not signed.

Two .INF files are needed rather than one because Passthru is installed both as a protocol and a miniport.

CODE TOUR

File Manifest

File           Description

Makefile       Used during compilation to create the object and sys files

Miniport.c     Miniport related functions of the passthru driver

Netsf.inf      Installation INF for the service (protocol side installation)

Netsf_m.inf    Installation INF for the miniport (virtual device installation)

Passthru.c     DriverEntry routine and any routines common to the passthru miniport and protocol

Passthru.h     Prototypes of all functions and data structures used by the Passthru driver

Passthru.htm   Documentation for the Passthru driver (this file)

Passthru.rc    Resource file for the Passthru driver

Precomp.h      Precompile header file

Protocol.c     Protocol related functions of the Passthru driver

Sources        List of source files that are compiled and linked to create the passthru driver. This can be modified to create binaries that operate on previous Windows versions (e.g. Windows 2000).

Programming Tour

Basic steps in initializing and halting of Passthru driver:

1) During DriverEntry, the Passthru driver registers as a protocol and an Intermediate miniport driver.

2) Later on, NDIS calls Passthru’s BindAdapterHandler, PtBindAdapter, for each underlying NDIS adapter to which it is configured to bind.

3) In the context of BindAdapterHandler and after successfully opening a binding to the underlying adapter, the Passthru driver queries the reserved keyword "UpperBindings" to get a list of device names for the virtual adapters that this particular binding is to expose. Since this driver implements a 1:1 relationship between lower bindings and virtual adapters, this list contains a single name. “Mux” IM drivers that expose multiple virtual adapters over a single underlying adapter will process multiple entries in UpperBindings.

4) For each device name, the Passthru driver calls NdisIMInitializeDeviceInstanceEx.

5) In response, NDIS will eventually call back Passthru miniport’s MiniportInitialize entry point, MPInitialize.

6) After MPInitialize successfully returns, NDIS takes care of getting upper-layer protocols to bind to the newly created virtual adapter(s).

7) All requests and sends coming from upper-layer protocols for the Passthru miniport driver are repackaged and sent down to NDIS, to be passed to the underlying NDIS adapter.

8) All indications arriving from bindings to an underlying NDIS adapter are forwarded up as if they generated from Passthru’s virtual adapters.

9) NDIS calls the Passthru driver’s ProtocolUnbind entry point to request it to close the binding between an underlying adapter and Passthru protocol. In processing this, the Passthru driver first calls NdisIMDeInitializeDeviceInstance for the virtual adapter(s) representing that particular binding.

10) NDIS in turn will close all the bindings between upper-layer protocols and virtual Passthru adapter.

11) After all the bindings are closed, NDIS calls the Passthru driver’s MiniportHalt entry point (MPHalt) for the virtual adapter.

12) The Passthru protocol then closes the binding to the underlying adapter by calling NdisCloseAdapter, and completes the unbind request issued in step 9.

13) Handling Power Management

13.1 During initialization, the Passthru miniport should set the Attribute 'NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND' in its call to NdisMSetAttributesEx.

13.2 When the Passthru miniport is requested to report its Plug and Play capabilities (OID_PNP_CAPABILITIES), the Passthru miniport must pass the request to the underlying miniport. If this request succeeds, then the Passthru miniport should overwrite the following fields before successfully completing the original request:

NDIS_DEVICE_POWER_STATE MinMagicPacketWakeUp = NdisDeviceStateUnspecified;

NDIS_DEVICE_POWER_STATE MinPatternWakeUp= NdisDeviceStateUnspecified;

NDIS_DEVICE_POWER_STATE MinLinkChangeWakeUp=NdisDeviceStateUnspecified

If the miniport below the Passthru protocol fails this request, then the status that was returned should be used to respond to the original request that was made to the Passthru miniport.

13.3 OID_PNP_SET_POWER and OID_PNP_QUERY_POWER should not be passed to the miniport below the Passthru protocol, as those miniports will receive independent requests from NDIS.

13.4 NDIS calls the Passthru driver’s ProtocolPnPEvent entry point (PtPnPHandler) whenever the underlying adapter is transitioned to a different power state. If the underlying adapter is transitioning to a low power state, the IM driver should wait for all outstanding sends and requests to complete.

14) NDIS 5.1 Features

14.1 All NDIS 5.1 features in Passthru are identified by #ifdef NDIS51 compiler directives. The following major features are illustrated (refer to the DDK documentation for more information on these):

Packet stacking: this allows an IM driver to reuse a packet submitted to its protocol or miniport edge to forward data down (or up) to the adjacent layer.

Canceling Sends: Passthru propagates send cancellations from protocols above it to lower miniports.

PnP Event Propagation: Passthru propagates PnP events arriving at its protocol (lower) edge to higher layer protocols that are bound to its virtual adapter.

NdisQueryPendingIOCount: Passthru uses this new API to determine if any I/O operations are in progress on its lower binding.

Top of page