\DDK\Src\Network\NDIS\SampIM
Both of these samples are useful. I doubt that either sample is bug-free.
Microsoft ImSamp Developer Notes
The Microsoft ImSamp NDIS Intermediate (IM) driver sample was
developed by Jim Mateer of Microsoft. Jim released several versions of ImSamp,
including the one on the Microsoft website.
The best approach is to start with the Microsoft
ImSamp sample from the Microsoft website as a baseline. Incorporate pieces from the
ImSamp Reference Sources if they are helpful.
PCAUSA has one version of ImSamp that is a slight variation
from the version on the Microsoft website. It should be considered as an unfinished work.
It includes an initial pruning DLL that attempts to review the bindings.
You can download this version of Jim Meteer's IMSAMP from:
Download ImSamp w/Prune DLL Driver
Sources
Use these sources at your own risk!!!
None of the available IM driver samples
are bug-free!!!
PCAUSA does NOT claim any credit for the
development of this or any version of ImSamp.
PCAUSA did make infinitesimal changes to the SOURCES file and slightly modified the ImSamp
directory structure.
ImSamp is built under the NT DDK using the BUILD tool. Please
read the NT DDK Help file for instructions on using BUILD.
Some versions of ImSamp included an interim NDIS.H and other
temporary NT DDK components.
At this time it is strongly suggested that you do
not use the interim NDIS.H and NDIS library components that came with some versions of
ImSamp. It is clear that the interim NDIS.H had bugs in certain macro definitions
which could cause problems even when building non-IM NDIS drivers.
The recommended environment for building an NDIS Intermediate driver is the Windows NT
5.0 Beta 3 DDK build environment. It includes the correct NDIS.H header and NDIS library.
The Microsoft Windows NT 5.0 DDK is available on the MSDN Universal Subscription CD. It
can also be downloaded from the Microsoft website.
Although the NT 5.0 DDK is needed to properly
build ImSamp, you can actually build ImSamp
and run it on a NT 4.0 (SP3+) platform.
If you already have the NT 4.0 DDK installed, you can install the NT 5.0 DDK without
overwriting your existing NT 4.0 DDK. Just specify a different root directory for the NT
5.0 DDK. After the installation you will have two separate NT DDK program groups.
Lets make this clear. You can:
So far PCAUSA has ONLY developed and tested ImSamp on NT 4.0 SP3 & SP4.
One last time: You need the NT 5.0
DDK. BUT you don't need NT 5.0!
Use the following steps to install the ImSamp Reference
Driver on the Windows NT 4.0 platform:
- You must copy BindPrune.DLL to your System32 directory before installing the IMSAMP
driver. This is the helper DLL that prunes the bindings during the review cycle.
- Copy DISK1, OEMSETUP.INF, BindPrune.DLL and IMSAMP.SYS to a floppy.
- In the NCPA, install a New Service. Select Have Disk, then select the floppy built in
Step 2.
NCPA will show the bindings as disabled after install, but they are really enabled.
1.) ImSamp uses the ProtocolReserved area of the NDIS_PACKET to contain a structure
named IM_PACKET_CONTEXT, defined in GLOBALS.H. The size of the IM_PACKET_CONTEXT is passed
to NdisAllocatePacketPool.
Some versions of the NT DDK documentation state:
"For packet descriptors to be used in receive indications, this parameter (i.e.,
the size of the ProtocolReserved area) can be at most 16 (bytes)".
Unfortunately, this statement is incorrect. The correct statement is:
"For packet descriptors to be used in receive indications, this parameter (i.e.,
the size of the ProtocolReserved area) must be at least 16
(bytes)"
When an IM driver is making a receive indication, it is operating as a miniport. In
this case, the IM driver is free to use the 8-byte MiniportReserved field of the
NDIS_PACKET when making indications.
Although it is not stated anywhere, the statement about the 16-byte minimum size of the
ProtocolReserved area when making indications must mean that some network component
(probably the NDIS wrapper) expects to be able to use these 16-bytes for some unspecified
purpose. It would also stand to reason that an IM driver could allocate a ProtocolReserved
size of greater then 16 bytes, and could use all but the first 16 bytes for its own
purpose when making receive indications.
2.) There is an additional problem associated with the definition of the NDIS_PACKET
structure. In some versions of NDIS.H, the NDIS_PACKET structure includes two ULONGs
before the ProtocolReserved field:
ULONG Reserved[2]; // For compatibility with Win95
UCHAR ProtocolReserved[1];
Unfortunately, these two ULONGs are NOT defined in the NT 4.0 DDK. So, there is some
question about were the ProtocolReserved area actually starts - at least on the NT 4.0
platform.
There is no good solution for this mixup.
The ImSamp driver, as currently written, is NOT a MINIPORT driver. This means that it
won't run as-is on Windows 9X.
- If one only looks for a solution that will allow ImSamp to run on Windows NT 4.0, then a
workaround for Problem 2 is to logically "comment out" the two Windows 95
Reserved ULONGs. One can do this by modifying use of the CONTAINING_RECORD macro to
reference Reserved[0] instead of ProtocolReserved when locating PIM_PACKET_RESERVED. In
this case, the size of IM_PACKET_RESERVED could be as large as 16 bytes. However, a
different solution would (probably) be required for Windows 2000.
- An approach that would (probably) work for Windows NT 4.0 and Windows 2000 is to use the
ProtocolReserved field location as defined in the Windows 2000 DDK (which includes the two
ULONGs) and reduce the size of the ProtocolReserved area to only 8 bytes.
3.) The attributes passed to NdisMSetAttributes should include
NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER.
NdisMSetAttributesEx(
MiniportAdapterHandle,
AdapterInList,
0,
NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER |
NDIS_ATTRIBUTE_DESERIALIZE |
NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT |
NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT,
0
);
If developers provide PCAUSA with bug fix information concerning the ImSamp
Reference Driver, then we will attempt to update it and maintain release notes as time
permits. Please understand that maintaining this FAQ is a fairly low priority task.
Working with NDISWAN/RAS and NDIS IM drivers has proven to be a difficult task. Here
are some notes from developers that have worked on this problem and have decided to share
their findings.
May 17, 1999 - Scott Meeuwsen <scottm@entela.com>
has contributed a paper that describes changes you can make to a working Ethernet IM
driver that will allow it to function with NDISWAN adapters over TCP/IP. Click the link
below to view Mr. Meeuwsen's paper.
How to make an IM driver that works with NDISWAN
over TCP/IP
Note: The approach described below by Andrew Zabolotny didn't work for Scott...
January 6, 1999 - Andrew Zabolotny <bit@eltech.ru>
has contributed a paper that includes his instructions on how to adapt a intermediate
driver that works with network cards to make it work with RAS. Click the link below to
view Mr. Zabolotny's paper.
Implementing An IM Driver That Works With RAS
Under NT
February 1, 1999 - At it's upper edge an NDIS Intermediate Driver should function like
an ordinary NDIS Miniport driver. This means that the Hardware Compatibility Test (HCT)
tools used to test ordinary NDIS Miniport drivers can be used to test NDIS Intermediate
Drivers.
NDIS Miniport drivers can be tested with the NDIS Tester, which is available from the
Microsoft WHQL (Windows Hardware Quality Labs). The general WHQL web site (for all kinds
of devices) is:
http://www.microsoft.com/hwtest 
Go to the TEST KITS & FAQs link and check the "LAN Network Self-Test"
entry in the table. There you'll find a link to the Hardware Compatibility Test (HCT)
CD-ROM, which you must order for a small fee.
There are also links for download of the latest test documents.
Alternatively, e.g. if you do not want to have your driver officially certified by WHQL,
download the latest NDIS Tester beta version from:
ftp://ftp.microsoft.com/services/whql/ndis
The NDIS Tester tests all of the Miniport driver's capabilities, depending if it is a
NDIS3, NDIS4, or NDIS5 Miniport.
In addition, some HCT Test Tools are included with the MSDN Universal Subscription CDs.
This FAQ, like
most others, is always under construction...
