|
|
<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-nothingpass-through NDIS 5 driver that demonstrates the basic principles underlying anNDIS Intermediate Miniport (IM) driver. This driver exposes a virtual adapterfor each binding to a real or virtual NDIS adapter. Protocols bind to thesevirtual 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 driverre-packages and sends down all requests and sends submitted to this virtualadapter. The Passthru driver can be modified to change the data before passingit along. For example, it could encrypt/compress outgoing anddecrypt/decompress incoming data.<o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>Passthru also re-packagesand indicates up all received data and status indications that it receives atits lower (protocol) edge.<o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>A related sample is the PASSTHRUnotification object sample found under network\ndis\Passthru\notifyob in thisDDK.<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 binaryPassthru.sys. <o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>To install this driver onWindows� 2000, use the PASSTHRU sample notification object and INFs, also foundin 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 asa 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 (orinstallation directory) that contains these files: netsf.inf, netsf_m.inf,passthru.sys and passthru.dll (notification object DLL, built in this DDK atnetwork\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 therelevant 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 thedrive/directory containing the files listed above. Click <b>OK</b>. This shouldshow �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 unsignedfiles. This is necessary because binaries generated via the DDK buildenvironment are not signed.<o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>Two .INF files are neededrather than one because Passthru is installed both as a protocol and aminiport.<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<spanstyle='mso-tab-count:1'>������ </span>Used during compilation to create the object and sys files</pre><pre>Miniport.c<spanstyle='mso-tab-count:1'>���� </span>Miniport related functions of the passthru driver</pre><pre>Netsf.inf<spanstyle='mso-tab-count:1'>����� </span>Installation INF for the service (protocol side installation)</pre><pre>Netsf_m.inf<spanstyle='mso-tab-count:1'>��� </span>Installation INF for the miniport (virtual device installation)</pre><pre>Passthru.c<spanstyle='mso-tab-count:1'>���� </span>DriverEntry routine and any routines common to the passthru miniport and protocol </pre><pre>Passthru.h<spanstyle='mso-tab-count:1'>���� </span>Prototypes of all functions and data structures used by the Passthru driver</pre><pre>Passthru.htm<spanstyle='mso-tab-count:1'>�� </span>Documentation for the Passthru driver (this file)</pre><pre>Passthru.rc<spanstyle='mso-tab-count:1'>��� </span>Resource file for the Passthru driver</pre><pre>Precomp.h<spanstyle='mso-tab-count:1'>����� </span>Precompile header file</pre><pre>Protocol.c<spanstyle='mso-tab-count:1'>���� </span>Protocol related functions of the Passthru driver</pre><pre>Sources<spanstyle='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 ininitializing 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 miniportdriver.<o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>2) Later on, NDIS callsPassthru�s BindAdapterHandler, PtBindAdapter, for each underlying NDIS adapterto 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 ofBindAdapterHandler and after successfully opening a binding to the underlyingadapter, the Passthru driver queries the reserved keyword"UpperBindings" to get a list of device names for the virtualadapters that this particular binding is to expose. Since this driverimplements a 1:1 relationship between lower bindings and virtual adapters, thislist contains a single name. �Mux� IM drivers that expose multiple virtualadapters over a single underlying adapter will process multiple entries inUpperBindings.<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 willeventually 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 successfullyreturns, NDIS takes care of getting upper-layer protocols to bind to the newlycreated virtual adapter(s).<o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>7) All requests and sendscoming from upper-layer protocols for the Passthru miniport driver arerepackaged 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 indicationsarriving from bindings to an underlying NDIS adapter are forwarded up as ifthey 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 thePassthru driver�s ProtocolUnbind entry point to request it to close the bindingbetween an underlying adapter and Passthru protocol. In processing this, thePassthru driver first calls NdisIMDeInitializeDeviceInstance for the virtualadapter(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 willclose all the bindings between upper-layer protocols and virtual Passthruadapter.<o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>11) After all thebindings 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 protocolthen 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 PowerManagement</b><o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>13.1 Duringinitialization, 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 Passthruminiport is requested to report its Plug and Play capabilities(OID_PNP_CAPABILITIES), the Passthru miniport must pass the request to theunderlying miniport. If this request succeeds, then the Passthru miniportshould overwrite the following fields before successfully completing theoriginal request: <o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>NDIS_DEVICE_POWER_STATE<spanstyle='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<spanstyle='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<spanstyle='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 thePassthru protocol fails this request, then the status that was returned shouldbe used to respond to the original request that was made to the Passthruminiport. <o:p></o:p></span></p>
<p><span style='font-size:10.0pt;font-family:Verdana'>13.3 OID_PNP_SET_POWERand OID_PNP_QUERY_POWER should not be passed to the miniport below the Passthruprotocol, 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 thePassthru driver�s ProtocolPnPEvent entry point (PtPnPHandler) whenever theunderlying adapter is transitioned to a different power state. If theunderlying adapter is transitioning to a low power state, the IM driver shouldwait 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.1features in Passthru are identified by #ifdef NDIS51 compiler directives. Thefollowing major features are illustrated (refer to the DDK documentation formore information on these):<o:p></o:p></span></p>
<p><b><span style='font-size:10.0pt;font-family:Verdana'>Packet stacking</span></b><spanstyle='font-size:10.0pt;font-family:Verdana'>: this allows an IM driver toreuse 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><spanstyle='font-size:10.0pt;font-family:Verdana'>: Passthru propagates sendcancellations 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><spanstyle='font-size:10.0pt;font-family:Verdana'>: Passthru propagates PnP eventsarriving at its protocol (lower) edge to higher layer protocols that are boundto its virtual adapter.<o:p></o:p></span></p>
<p><b><span style='font-size:10.0pt;font-family:Verdana'>NdisQueryPendingIOCount</span></b><spanstyle='font-size:10.0pt;font-family:Verdana'>: Passthru uses this new API todetermine 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'><spanstyle="mso-spacerun: yes">�</span><o:p></o:p></span></p>
<p align=center style='text-align:center'><a href="#top"><spanstyle='font-size:10.0pt;font-family:Verdana'>Top of page</span></a><spanstyle='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 MicrosoftCorporation</span><span style='font-size:10.0pt;font-family:Verdana'> <o:p></o:p></span></p>
</div>
</body>
</html>
|
