367 lines
16 KiB
HTML
367 lines
16 KiB
HTML
<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<6C>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<EFBFBD> 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 <20>Passthru Driver<65> 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 <20>Passthru Driver<65> 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'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </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'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Used during compilation to create the object and sys files</pre><pre>Miniport.c<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Miniport related functions of the passthru driver</pre><pre>Netsf.inf<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Installation INF for the service (protocol side installation)</pre><pre>Netsf_m.inf<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD> </span>Installation INF for the miniport (virtual device installation)</pre><pre>Passthru.c<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>DriverEntry routine and any routines common to the passthru miniport and protocol </pre><pre>Passthru.h<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Prototypes of all functions and data structures used by the Passthru driver</pre><pre>Passthru.htm<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD> </span>Documentation for the Passthru driver (this file)</pre><pre>Passthru.rc<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD> </span>Resource file for the Passthru driver</pre><pre>Precomp.h<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Precompile header file</pre><pre>Protocol.c<span
|
||
style='mso-tab-count:1'><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </span>Protocol related functions of the Passthru driver</pre><pre>Sources<span
|
||
style='mso-tab-count:2'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </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<EFBFBD>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. <20>Mux<75> 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<72>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<72>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<65>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<65>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'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </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'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </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'><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> </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<65>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"><EFBFBD></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"'><EFBFBD> 1999 Microsoft
|
||
Corporation</span><span style='font-size:10.0pt;font-family:Verdana'> <o:p></o:p></span></p>
|
||
|
||
</div>
|
||
|
||
</body>
|
||
|
||
</html>
|