mirror of https://github.com/tongzx/nt5src
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
366 lines
16 KiB
366 lines
16 KiB
<html xmlns:v="urn:schemas-microsoft-com:vml"
|
|
xmlns:o="urn:schemas-microsoft-com:office:office"
|
|
xmlns:w="urn:schemas-microsoft-com:office:word"
|
|
xmlns="http://www.w3.org/TR/REC-html40">
|
|
|
|
<head>
|
|
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
|
|
<meta name=ProgId content=Word.Document>
|
|
<meta name=Generator content="Microsoft Word 9">
|
|
<meta name=Originator content="Microsoft Word 9">
|
|
<link rel=File-List href="./passthru_files/filelist.xml">
|
|
<title>passthru</title>
|
|
<style>
|
|
<!--
|
|
/* Font Definitions */
|
|
@font-face
|
|
{font-family:"MS Sans Serif";
|
|
panose-1:0 0 0 0 0 0 0 0 0 0;
|
|
mso-font-charset:0;
|
|
mso-generic-font-family:swiss;
|
|
mso-font-format:other;
|
|
mso-font-pitch:variable;
|
|
mso-font-signature:3 0 0 0 1 0;}
|
|
@font-face
|
|
{font-family:Verdana;
|
|
panose-1:2 11 6 4 3 5 4 4 2 4;
|
|
mso-font-charset:0;
|
|
mso-generic-font-family:swiss;
|
|
mso-font-pitch:variable;
|
|
mso-font-signature:536871559 0 0 0 415 0;}
|
|
/* Style Definitions */
|
|
p.MsoNormal, li.MsoNormal, div.MsoNormal
|
|
{mso-style-parent:"";
|
|
margin:0in;
|
|
margin-bottom:.0001pt;
|
|
mso-pagination:widow-orphan;
|
|
font-size:12.0pt;
|
|
font-family:"Times New Roman";
|
|
mso-fareast-font-family:"Times New Roman";
|
|
color:black;}
|
|
h2
|
|
{margin-right:0in;
|
|
mso-margin-top-alt:auto;
|
|
mso-margin-bottom-alt:auto;
|
|
margin-left:0in;
|
|
mso-pagination:widow-orphan;
|
|
mso-outline-level:2;
|
|
font-size:18.0pt;
|
|
font-family:"Times New Roman";
|
|
color:black;
|
|
font-weight:bold;}
|
|
h3
|
|
{margin-right:0in;
|
|
mso-margin-top-alt:auto;
|
|
mso-margin-bottom-alt:auto;
|
|
margin-left:0in;
|
|
mso-pagination:widow-orphan;
|
|
mso-outline-level:3;
|
|
font-size:13.5pt;
|
|
font-family:"Times New Roman";
|
|
color:black;
|
|
font-weight:bold;}
|
|
h4
|
|
{margin-right:0in;
|
|
mso-margin-top-alt:auto;
|
|
mso-margin-bottom-alt:auto;
|
|
margin-left:0in;
|
|
mso-pagination:widow-orphan;
|
|
mso-outline-level:4;
|
|
font-size:12.0pt;
|
|
font-family:"Times New Roman";
|
|
color:black;
|
|
font-weight:bold;}
|
|
a:link, span.MsoHyperlink
|
|
{color:blue;
|
|
text-decoration:underline;
|
|
text-underline:single;}
|
|
a:visited, span.MsoHyperlinkFollowed
|
|
{color:purple;
|
|
text-decoration:underline;
|
|
text-underline:single;}
|
|
p
|
|
{margin-right:0in;
|
|
mso-margin-top-alt:auto;
|
|
mso-margin-bottom-alt:auto;
|
|
margin-left:0in;
|
|
mso-pagination:widow-orphan;
|
|
font-size:12.0pt;
|
|
font-family:"Times New Roman";
|
|
mso-fareast-font-family:"Times New Roman";
|
|
color:black;}
|
|
pre
|
|
{margin:0in;
|
|
margin-bottom:.0001pt;
|
|
mso-pagination:widow-orphan;
|
|
tab-stops:45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;
|
|
font-size:10.0pt;
|
|
font-family:"Courier New";
|
|
mso-fareast-font-family:"Courier New";
|
|
color:black;}
|
|
@page Section1
|
|
{size:8.5in 11.0in;
|
|
margin:1.0in 1.25in 1.0in 1.25in;
|
|
mso-header-margin:.5in;
|
|
mso-footer-margin:.5in;
|
|
mso-paper-source:0;}
|
|
div.Section1
|
|
{page:Section1;}
|
|
-->
|
|
</style>
|
|
<!--[if gte mso 9]><xml>
|
|
<o:shapedefaults v:ext="edit" spidmax="1027"/>
|
|
</xml><![endif]--><!--[if gte mso 9]><xml>
|
|
<o:shapelayout v:ext="edit">
|
|
<o:idmap v:ext="edit" data="1"/>
|
|
</o:shapelayout></xml><![endif]-->
|
|
<meta name=Template content="C:\Program Files\Microsoft Office\Office\html.dot">
|
|
</head>
|
|
|
|
<body bgcolor=white lang=EN-US link=blue vlink=purple style='tab-interval:.5in'>
|
|
|
|
<div class=Section1>
|
|
|
|
<h2><a name=MYSAMPLE></a><a name=top></a><span style='mso-bookmark:MYSAMPLE'>
|
|
|
|
<!doctype HTML>
|
|
|
|
<span style='font-family:Verdana'><! ---------------- Snip Snip ---------------- >PASSTHRU.SYS
|
|
- Sample NDIS Intermediate Driver</span></span><span style='font-family:Verdana'><o:p></o:p></span></h2>
|
|
|
|
<h3><span style='font-family:Verdana'>SUMMARY<o:p></o:p></span></h3>
|
|
|
|
<p><b><span style='font-family:Verdana'>Passthru Intermediate Miniport Driver<o:p></o:p></span></b></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Passthru also re-packages
|
|
and indicates up all received data and status indications that it receives at
|
|
its lower (protocol) edge.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>A related sample is the PASSTHRU
|
|
notification object sample found under network\ndis\Passthru\notifyob in this
|
|
DDK.<o:p></o:p></span></p>
|
|
|
|
<h3><span style='font-family:Verdana'>BUILDING THE SAMPLE<o:p></o:p></span></h3>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Run the <b>build</b>
|
|
command from this directory to build the sample—it creates the binary
|
|
Passthru.sys. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>To install this driver on
|
|
Windows® 2000, use the PASSTHRU sample notification object and INFs, also found
|
|
in this DDK.<o:p></o:p></span></p>
|
|
|
|
<h3><span style='font-family:Verdana'>INSTALLING THE SAMPLE<o:p></o:p></span></h3>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Passthru is installed as
|
|
a service (called “Passthru Driver” in the supplied INFs/notification object).
|
|
To install, follow the steps below.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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).<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>On the desktop,
|
|
right-click the <b>My Network Places</b> icon and choose <b>Properties</b>. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Right-click on the
|
|
relevant Local Area Connection icon and choose <b>Properties</b>. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Click <b>Install</b>,
|
|
then <b>Service</b>, then <b>Add</b>, then <b>Have Disk</b>. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Browse to the
|
|
drive/directory containing the files listed above. Click <b>OK</b>. This should
|
|
show “Passthru Driver” in a list of Network Services. Highlight this and click <b>OK</b>.
|
|
This should install the Passthru driver. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Click <b>OK</b> or <b>Yes</b>
|
|
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.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Two .INF files are needed
|
|
rather than one because Passthru is installed both as a protocol and a
|
|
miniport.<o:p></o:p></span></p>
|
|
|
|
<h3><span style='font-family:Verdana'>CODE TOUR<o:p></o:p></span></h3>
|
|
|
|
<h4><span style='font-family:Verdana'>File Manifest<o:p></o:p></span></h4>
|
|
|
|
<pre><u>File<span style='mso-tab-count:2'> </span>Description<o:p></o:p></u></pre><pre><![if !supportEmptyParas]> <![endif]><o:p></o:p></pre><pre>Makefile<span
|
|
style='mso-tab-count:1'> </span>Used during compilation to create the object and sys files</pre><pre>Miniport.c<span
|
|
style='mso-tab-count:1'> </span>Miniport related functions of the passthru driver</pre><pre>Netsf.inf<span
|
|
style='mso-tab-count:1'> </span>Installation INF for the service (protocol side installation)</pre><pre>Netsf_m.inf<span
|
|
style='mso-tab-count:1'> </span>Installation INF for the miniport (virtual device installation)</pre><pre>Passthru.c<span
|
|
style='mso-tab-count:1'> </span>DriverEntry routine and any routines common to the passthru miniport and protocol </pre><pre>Passthru.h<span
|
|
style='mso-tab-count:1'> </span>Prototypes of all functions and data structures used by the Passthru driver</pre><pre>Passthru.htm<span
|
|
style='mso-tab-count:1'> </span>Documentation for the Passthru driver (this file)</pre><pre>Passthru.rc<span
|
|
style='mso-tab-count:1'> </span>Resource file for the Passthru driver</pre><pre>Precomp.h<span
|
|
style='mso-tab-count:1'> </span>Precompile header file</pre><pre>Protocol.c<span
|
|
style='mso-tab-count:1'> </span>Protocol related functions of the Passthru driver</pre><pre>Sources<span
|
|
style='mso-tab-count:2'> </span>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).</pre>
|
|
|
|
<h4><span style='font-family:Verdana'>Programming Tour<o:p></o:p></span></h4>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>Basic steps in
|
|
initializing and halting of Passthru driver:<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>1) During DriverEntry,
|
|
the Passthru driver registers as a protocol and an Intermediate miniport
|
|
driver.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>2) Later on, NDIS calls
|
|
Passthru’s BindAdapterHandler, PtBindAdapter, for each underlying NDIS adapter
|
|
to which it is configured to bind.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>4) For each device name,
|
|
the Passthru driver calls NdisIMInitializeDeviceInstanceEx.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>5) In response, NDIS will
|
|
eventually call back Passthru miniport’s MiniportInitialize entry point,
|
|
MPInitialize.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>6) After MPInitialize successfully
|
|
returns, NDIS takes care of getting upper-layer protocols to bind to the newly
|
|
created virtual adapter(s).<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>8) All indications
|
|
arriving from bindings to an underlying NDIS adapter are forwarded up as if
|
|
they generated from Passthru’s virtual adapters.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>10) NDIS in turn will
|
|
close all the bindings between upper-layer protocols and virtual Passthru
|
|
adapter.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>11) After all the
|
|
bindings are closed, NDIS calls the Passthru driver’s MiniportHalt entry point
|
|
(MPHalt) for the virtual adapter.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>12) The Passthru protocol
|
|
then closes the binding to the underlying adapter by calling NdisCloseAdapter,
|
|
and completes the unbind request issued in step 9.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>13) <b>Handling Power
|
|
Management</b><o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>13.1 During
|
|
initialization, the Passthru miniport should set the Attribute '<i>NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND</i>'
|
|
in its call to NdisMSetAttributesEx. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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: <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>NDIS_DEVICE_POWER_STATE<span
|
|
style='mso-tab-count:1'> </span>MinMagicPacketWakeUp =
|
|
NdisDeviceStateUnspecified;<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>NDIS_DEVICE_POWER_STATE<span
|
|
style='mso-tab-count:1'> </span>MinPatternWakeUp=
|
|
NdisDeviceStateUnspecified;<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>NDIS_DEVICE_POWER_STATE<span
|
|
style='mso-tab-count:1'> </span>MinLinkChangeWakeUp=NdisDeviceStateUnspecified<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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. <o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>14) <b>NDIS 5.1 Features</b><o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'>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):<o:p></o:p></span></p>
|
|
|
|
<p><b><span style='font-size:10.0pt;font-family:Verdana'>Packet stacking</span></b><span
|
|
style='font-size:10.0pt;font-family:Verdana'>: 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.<o:p></o:p></span></p>
|
|
|
|
<p><b><span style='font-size:10.0pt;font-family:Verdana'>Canceling Sends</span></b><span
|
|
style='font-size:10.0pt;font-family:Verdana'>: Passthru propagates send
|
|
cancellations from protocols above it to lower miniports.<o:p></o:p></span></p>
|
|
|
|
<p><b><span style='font-size:10.0pt;font-family:Verdana'>PnP Event Propagation</span></b><span
|
|
style='font-size:10.0pt;font-family:Verdana'>: Passthru propagates PnP events
|
|
arriving at its protocol (lower) edge to higher layer protocols that are bound
|
|
to its virtual adapter.<o:p></o:p></span></p>
|
|
|
|
<p><b><span style='font-size:10.0pt;font-family:Verdana'>NdisQueryPendingIOCount</span></b><span
|
|
style='font-size:10.0pt;font-family:Verdana'>: Passthru uses this new API to
|
|
determine if any I/O operations are in progress on its lower binding.<o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'><![if !supportEmptyParas]> <![endif]><o:p></o:p></span></p>
|
|
|
|
<p><span style='font-size:10.0pt;font-family:Verdana'><span
|
|
style="mso-spacerun: yes"> </span><o:p></o:p></span></p>
|
|
|
|
<p align=center style='text-align:center'><a href="#top"><span
|
|
style='font-size:10.0pt;font-family:Verdana'>Top of page</span></a><span
|
|
style='font-size:10.0pt;font-family:Verdana'> <o:p></o:p></span></p>
|
|
|
|
<table border=0 cellspacing=0 cellpadding=0 width=624 style='width:6.5in;
|
|
mso-cellspacing:0in;mso-padding-alt:0in 0in 0in 0in'>
|
|
<tr style='height:1.5pt'>
|
|
<td style='background:aqua;padding:.75pt .75pt .75pt .75pt;height:1.5pt'>
|
|
<p class=MsoNormal><![if !supportEmptyParas]> <![endif]><o:p></o:p></p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span style='font-size:7.5pt;font-family:"MS Sans Serif"'>© 1999 Microsoft
|
|
Corporation</span><span style='font-size:10.0pt;font-family:Verdana'> <o:p></o:p></span></p>
|
|
|
|
</div>
|
|
|
|
</body>
|
|
|
|
</html>
|