Guten Tag
Wie kann ich unter XP diesen Treiber nutzen?
Der war im win2003 ddk enthalten
Sample NDIS-WDM Miniport Driver
SUMMARY
The purpose of this sample is to illustrate functionality of an NDIS-WDM miniport driver. An NDIS-WDM driver exposes NDIS miniport interface at its upper edge and uses IRPs to interact with other WDM drivers such as USB, IEEE 1394, and serial at its lower edge. Unlike NDIS miniports, which can call only NDIS functions, an NDIS-WDM driver can call both NDIS and non-NDIS functions. However, whenever possible, the miniport driver should call NDIS functions. For example, a miniport driver that controls devices on either Universal Serial Bus (USB) or IEEE 1394 (firewire) buses must expose a standard NDIS miniport driver interface at its upper edge and use the class interface for the particular bus at its lower edge. Such a miniport driver communicates with devices that are attached to the bus by sending I/O request packets (IRPs) to the bus.
This sample is built upon the NETVMINI sample available in the Windows Server 2003 DDK. Unlike the NETVMINI, this sample is fully functional. It uses the NDISPROT (NDIS protocol sample available in the Windows Server 2003 DDK) as its lower WDM edge driver to read and write packets to the physical network interface card (NIC) as shown in the diagram below. In order to test this sample, you should at least have one physical NIC on the test machine.
---------------------
| |
| TCP/IP |
| |
---------------------
^
| <-------------- NDIS Interface
V
---------------------
| |
| Sample NDISWDM |
| Miniport |
| |
---------------------
^
| <--------------- IRPs
V
---------------------
| |
| NDISPROT |
| |
---------------------
^
| <--------------- NDIS Interface
V
---------------------
| |
| NDIS Miniport |
| for physical NIC |
| |
---------------------
^
| <-------------- Talk to the hardware using I/O resources
V
---------------
| H/w NIC |
---------------
|||||||
-------
Note: This sample provides an example of a minimal driver intended for educational purposes. Neither the driver nor its sample test programs are intended for use in a production environment.
Operating System
Can sample be built in the OS? Does sample work in the OS? Can sample be used in a production environment for the OS?
Windows Server 2003 Yes Yes No
Windows XP Yes Yes No
Windows 2000 Yes Yes No
Windows Me
See Compatibility below.
See Compatibility below.
No
Windows 98 SE
See Compatibility below.
See Compatibility below.
No
The driver can be built in the Windows® 2000, Windows® XP, and Server 2003 DDK build environment.
The driver can be installed in the Windows 2000, XP, and Server 2003 operating systems. Windows 2000 supports only NDIS version 5.0 miniport driver. Windows XP and Server 2003 support NDIS versions 5.0 and 5.1 of miniport driver.
BUILDING THE SAMPLE
Click the Free Build Environment or Checked Build Environment icon under your Development Kit's program group to set basic environment variables needed by the build utility.
Change to the directory containing the device source code, such as CD Src\network\ndis\NDISWDM.
Run build -ceZ, or use the macro BLD. Using these tools invokes the Microsoft make routines that produce log files called Buildxxx_yyy_zzz.log, and also Buildxx_yyy_zzz.wrn and Buildxx_yyy_zzz.err if there are any warnings or errors. Where xxx stands for fre or chk depending on the environment chosen, yyy stands for the OS version (W2K, WXP, or Wnet), and zzz stands for platform version (x86, IA64, or AMD64).
If the build succeeds, the driver, ndiswdm.sys, will be placed in a platform specific subdirectory of your %TargetPath% directory specified in the 'Sources' file. Depending on the build environment, the driver will be either an NDIS 5.0 or NDIS 5.1 miniport driver. If you build in the Windows 2000 build environment, you will get NDIS version 5.0 of the miniport driver. If you build in the Windows XP or Server 2003 environments, you will get NDIS version 5.1 of the miniport driver.
INSTALLATION
You can install the NDISWDM driver and use it as your primary miniport by doing one of the following:
* Disable the bindings of TCP/IP with the physical NIC's miniport and have the NDISWDM miniport to assume the MAC address of the physical NIC. This is the default case.
* Don't alter the bindings of TCP/IP with the physical NICs miniport. Instead, have the NDISWDM miniport set the physical NIC into Promiscuous mode by using the Advanced Property dialog of NDISWDM in the Device Manager. This way, the NDISWDM can send and receive packets that have different MAC addresses. In this mode, the NDISWDM miniport generates its own locally administered MAC address instead of using the physical NIC's MAC address as its current address.
Installation steps
1. Install the NDISPROT sample from the Windows Server 2003 DDK and start the driver. Instruction on how to install and load the driver is given in the NDISPROT.HTM that comes with the sample. Make sure to rebuild the driver with EX_CALLBACK interface defined in the 'Sources' file. This enables the driver to notify NDISWDM whenever it gets loaded. Read the Code Tour section in this document for further information.
2. Double-click Network Connections in Control panel, right-click the Local Area Connection applet of the physical NIC, and select Properties. Clear the TCP/IP bindings check box.
3. Install the NDISWDM miniport driver. Steps for installing the driver on Windows 2000, XP, and Server 2003 DDK are listed below:
To install the driver on a Windows 2000 machine
1. Build the driver in a Win2K build environment to get the NDIS version 5.0 of the driver.
2. Copy the driver and the NDISWDM.INF file to a floppy disk or to a directory on the target test machine.
3. Open Control Panel, and double-click Add New Hardware.
4. Click Next.
5. Select Add a new device.
6. Select No, I Want to Select the Hardware from a list.
7. Select Network Devices, and then click Next.
8. Click Have Disk, and point to the directory that contains NDISWDM.INF file.
To install the driver on a Windows XP or Server 2003 machine
1. Copy the NDIS version 5.1 of the driver and the INF file to a floppy disk or to a directory on the target machine.
2. Open Control Panel and double-click Add Hardware.
3. At the Welcome to the Add Hardware Wizard screen, click Next.
4. Select Yes, I have already connected the hardware, and click Next.
5. Select Add a new hardware device from the list, and click Next.
6. Select Install the hardware that I manually select from a list (Advanced), and click Next.
7. Select Network adapters, and click Next.
8. Click Have Disk, make sure that A:\ is in the Copy manufacturer's files from box, and click OK.
9. Click on the desired entry, and click Next.
10. At The wizard is ready to install your hardware screen, click Next.
11. Click Finish.
Alternatively, you can use the DEVCON.EXE from the DDK to install the driver programmatically.
c:\>DEVCON.EXE INSTALL ndiswdm.inf "root\ndiswdm"
The system copies the NDISWDM.sys file to %systemroot%\system32\drivers directory and loads the driver. Instead of root-enumerating the driver as described above, you can use the toaster bus driver to bus enumerate the driver.
4. Check the configuration of the miniport by running IPCONFIG /All. You should be able to browse the internet or copy files from another machine.
This the default configuration - NDISPROT driver is started before NDISWDM miniport - and the miniport is using the MAC address of the real NIC. If you reboot the machine, you will notice that the network connectivity through the miniport is broken. This is because the NDISPROT hasn't been loaded or loaded after the miniport. When the miniport fails to open the NDISPROT interface during init, it reports a locally administered MAC address as the current address and completes the initialization. After that, even if the miniport is able to successfully open the NDISPROT interface in the ExCallback, it cannot report the Real NIC's MAC address. As a result, no network communication will take place because the real NIC will not receive or send packets that doesn't match with it's MAC address. In such a scenario, you can re-establish the network connectivity by disabling and re-enabling the miniport instance in the device manager to make sure that the miniport opens the target device during MiniportInitialize and reports the target NIC's MAC address.
If you like to get this configuration to work across reboots, you should configure the NDISWDM driver to set the target NIC filter to promiscuous mode. You can do that by using Advanced Property of the miniport in the device manager or by changing the value in the INF file before installing the miniport.
TESTING
Install NDIS Tester from the WHQL Web site and run all the client and server tests.
CODE TOUR
The information below describes some of the key operations performed in the driver.
Initialization
1. Allocates memory for miniport context structure. This is where the driver stores information about a specific instance of the device.
2. In the NICInitializeAdapter, the driver tries to open the NDISPROT device by using ZwOpenFile("\Device\NdisProt").
3. If the call fails because the NDISPROT is not loaded, the driver registers an executive callback interface to be notified whenever the NDISPROT loads. If the call succeeds, the driver gets the target deviceobject related to the file handle returned by ZwOpenFile. The driver then sends IOCTL_NDISPROT_QUERY_BINDING to query the list of miniport device names and a message that NDISPROT is bound to in a loop.
4. At every iteration in the loop, the driver makes sure that the miniport name and description it received from the NDISPROT is not one of its own (in case multiple instances of NDISWDM are installed). The driver then makes an IOCTL_NDISPROT_OPEN_DEVICE request to open the target device. If the request fails, the driver continues the loop until it finds a free one.
5. If the IOCTL_NDISPROT_OPEN_DEVICE request succeeds, the driver allocates resources for handling send and receive requests, sends IOCTL requests to NDISPROT to get the link speed, sets the miniport to Promiscuous mode (if enabled in the registry), and finally creates a worker thread to poll for read packets from the NDISPROT.
Resolving driver load order issue between NDISWDM and NDISPROT:
NDISWDM and NDISPROT driver are two unrelated drivers. NDISWDM is a Plug and Play driver and NDISPROT is an Windows®NT®4.0 compatible non-Plug and Play driver. As a result, it's not possible to use a Plug and Play notification mechanism to resolve load order dependency between the drivers. If the NDISWDM is installed as a root-enumerated driver, then it will get loaded much earlier in the boot sequence than the NDISPROT driver. When the NDISWDM tries to open the NDISPROT in MiniportInitialize handler, it will fail with a STATUS_OBJECT_NAME_NOT_FOUND error because the NDISPROT device is not present.
Instead of using timer DPCs and work items to periodically retry opening NDISPROT, this driver uses a new executive callback mechanism to resolve the load order issue. Both NDISWDM and NDISPROT create a Callback object (ExCreateCallback) called \Callback\NdisProtCallbackObject and register their callback handlers (ExRegisterCallback). The driver that loads first creates the object and the drivers loaded afterwards open the same object, register, and then send notification to the other drivers. Based on the notification ID received in the callback, both NDISWDM and NDISPROT identify the source of notification and take appropriate action. For example, when the NDISWDM driver receives a notification, it checks to see if the source driver of this notification is NDISPROT and if so, it tries to complete its initialization and indicate the final media status of its miniport to NDIS.
Request Handler
Most of the requests are handled directly by the NDISWDM and completed synchronously. The driver also has the ability to forward any requests to the target driver. For forwarding requests, such as link speed, it queues a work item to get to PASSIVE_LEVEL of execution, and from the workitem it sends an IOCTL request to NDISPROT and waits for the IRP to complete. When the IRP returns, it indicates to NDIS about the completion of the request.
Send Packet Handler
In the SendPacket handler, the driver copies the packet into a free TCB block (because NDISPROT cannot handle chained MDLs), initializes a preallocated IRP (IRP_MJ_WRITE) and MDL to describe the TCB data buffer and sends the IRP to the NDISPROT driver asynchronously. When the write completes, the original send packet that was saved in the TCB control block is completed and the TCB and IRP is freed for reuse.
Receive Packet handler:
The driver pre-allocates a certain number (NIC_MAX_BUSY_SENDS) of RCB (Receive Control Blocks) buffers, IRPs (IRP_MJ_READ) and MDLs (to describe the RCB data buffer) during Miniport Initialize for receiving packets from the target driver (NDISPROT). It then queues a workitmem (NICPostReadsWorkItemCallBack) to post all the read IRPs to the target driver. When a read request completes, the completion routine (NICReadRequestCompletion) is called. This routine checks to see whether the received packet is acceptable based on the current packet filter set by the protocol, and decides to either indicate the packet to NDIS or discard the packet. When the indicated packet returns from NDIS through MPReturnPacket handler, the driver reclaims the associated RCB block and the read IRP for reuse, and checks to see if the number of outstanding Read IRPs to the NDISPROT has gone below a certain thershold (NIC_SEND_LOW_WATERMARK). If so, it queues a workitem to post more read IRPs and keeps the read path going.
Adapting this driver for an USB device
If you are using this sample to build an NDIS miniport driver for an USB device:
* First, update the Hardware ID specified in the INF file to that of your USB device. As a result, when you plug in the device, and if the INF file is pre-installed (SetupCopyOEMInf), the PNP manager will automatically pickup your miniport as the driver for the USB device.
* Remove all the code that are specific to interacting with NDISPROT. You don't have to open a USB device by calling Zw function. Your driver will be part of the USB device stack and your TargetDeviceObject will be the NextDeviceObject received from NdisGetDeviceProperty call.
* In the NICInitAdapterWorker routine, right before you allocate send & receive side resources, configure your USB device. You can either follow the BULKUSB sample present in the DDK or Walter Oney's Programming Windows Driver Model, Second Edition, book sample code to learn about how to build and submit URB requests to configure your device.
* Once you have all the worker routines for building and submitting URBs are in place, and all the appropriate transfer pipes are setup, you can convert read, write, and IOCTL requests to corresponding URB's and send it to the USB stack.
RESOURCES
For the latest release of the Windows device Driver Development Kit, see www.microsoft.com.
If you have questions on using or adapting this sample for your project, you can either contact Microsoft Technical Support or post your questions in the Microsoft driver development newsgroup.
COMPATIBILITY
This driver has not been tested on Windows Me, Windows 98, Windows 95 or earlier systems. However, this driver can be easily made to work if there is an equivalent to NDISPROT that works on these systems. One of the WinHEC 2000 presentations discusses some of issues that should be addressed in this sample to make it work on Windows Me, Windows 98, Windows 95 or earlier systems.
FILE MANIFEST (Optional)
File Description
ndiswdm.htm Sample Tour documentation for this sample (this file).
Sources Generic file for building the code sample.
ndiswdm.inf INF file for installing the driver.
ndiswdm.RC Resource file to specify driver version, etc.
ndiswdm.h Include file for defining structures, constants and function prototypes.
ndiswdm.c Main file that contains driver entry and other miniport functions.
init.c Source file for allocating and initializing resources.
send.c Source file for handling Send requests from NDIS.
receive.c Source file for handling IRPs received by the lower WDM driver indicating to NDIS.
request.c Source file for handling set & query information requests from NDIS.
excallbk.c Source file for handling ex callback notification to resolve driver load order.
Top of page
© 2003 Microsoft Corporation. All rights reserved.
Und was genau simuliert der Treiber eigentlich?
Danke für eure Hilfe