+
+
+
+
+
+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.
+
+
BUILDING THE SAMPLE
+
+
Run the build
+command from this directory to build the sampleit 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 and passthru.sys.
+
+
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 Passthrus 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 miniports 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 Passthrus virtual adapters.
+
+
9) NDIS calls the Passthru drivers 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 drivers 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 drivers 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.
+
+
15) For Win2K SP2 and WinXP, the Passthru sample no
+longer requires a Notify Object. The Notify Object has been removed.
+
+
+
+
Top of page
+
+
+
+
© 1999 Microsoft
+Corporation
+
+