|
|
Frequently Asked QuestionsQ. How can I adapt NDISUIO to work on Windows 98/ME?
| ||||||||||||||||||||
 | Handling Receives in a Deserialized Miniport Drivers on 9X/ME Platforms |
| NDIS Binary-Compatibility on Windows 98 and Windows 2000 |
X-Tomcat-ID: 775934918
References: <e4AqibBqDHA.392@TK2MSFTNGP11.phx.gbl>
<iH1PEGCqDHA.2396@cpmsftngxa06.phx.gbl> <uNfJkICqDHA.2416@TK2MSFTNGP10.phx.gbl>
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="----=_NextPart_0001_3DD23A19"
Content-Transfer-Encoding: 7bit
From: bburgin@online.microsoft.com ("Bryan S. Burgin [MSFT]")
Organization: Microsoft
Date: Tue, 11 Nov 2003 20:27:16 GMT
Subject: Re: NDISUIO and Windows 98
X-Tomcat-NG: microsoft.public.development.device.drivers
Message-ID: <h2vP2IJqDHA.576@cpmsftngxa06.phx.gbl>
Newsgroups: microsoft.public.development.device.drivers
Lines: 822
NNTP-Posting-Host: TOMCATIMPORT2 10.201.218.182
I had to make three modifications:
1) In general, your BindAdapter handler will get called with an adapter name and
you just take what you're given and pass it to NdisOpenAdapter.
NDISUIO/NDISPROT is different because it takes that name and stores it away in a structure for re-use later (like when a user-mode caller asks to enumerate the bound devices). While your code is built using a NT-based environment of the DDK (Win2K, XP, WS2003), it believes that this NDIS_STRING's buffer is Unicode. However, when you run this binary in 9x/ME, the buffer is ANSI. Still, the general rule (what you receive in your handler is what you pass to OpenAdapter) remains, just pass the pointer to NdisOpenAdapter. However, when you save the copy for future use, convert it to Unicode and save it that way - otherwise, there's too many other changes to make if you save it as ANSI. You can do this only when running on 9x/ME, and there are ways to determine what platform you're running on at run time.
2) I noticed that the user-mode application was opening "\\\\.\\\\xxxx" instead of "\\\\.\\xxxx" (one too many backslashes). This works in 2K, etc, but not in 9x. It should be fixed in the sample, if it's not already.
3) The INF is completely different. Below is the 9x version of the INF for NDISUIO. You should go to the extra trouble of making this a multi-platform INF so that the same INF can be used across all platforms.
BTW, on Windows ME, you MUST specify "Ndis3,Ndis4,Ndis5".
Also see my list of issues at the very bottom. I wrote these a long time ago and have not revisited the list, so it’s “as is”.
Hope this helps.
Bryan S. Burgi
This posting is provided "AS IS" with no warranties, and confers no rights.
; NDISUIO.INF ; ; NDISUIO Transport ; ; Copyright 2001, Microsoft Corporation
[version] signature="$CHICAGO$" Class=NetTrans provider=%V_MS%
[Manufacturer] %V_MS%=MS
[MS] %NDISUIO.DeviceDesc%= NDISUIO.ndi, NDISUIO
;*************************************************************************** ; NDISUIO ;***************************************************************************
[NDISUIO.ndi] CopyFiles=NDISUIO.CopyFiles AddReg=NDISUIO.ndi.reg DeviceID=NDISUIO MaxInstance=8
[NDISUIO.ndi.reg] HKR,Ndi,DeviceID,,NDISUIO HKR,Ndi,MaxInstance,,8
;;;HKR,Ndi,NdiInstaller,,"MyNdi.dll,MyNdiProc"
; NDIS info HKR,NDIS,LogDriverName,,"NDISUIO" HKR,NDIS,MajorNdisVersion,1,05 HKR,NDIS,MinorNdisVersion,1,00
; Interfaces HKR,Ndi\Interfaces,DefUpper,,"" HKR,Ndi\Interfaces,DefLower,,"ndis3,ndis4,ndis5" HKR,Ndi\Interfaces,UpperRange,,"" HKR,Ndi\Interfaces,LowerRange,,"ndis3,ndis4,ndis5"
; Install-Remove Sections HKR,Ndi\Install,,,"NDISUIO.Install" HKR,Ndi\Remove,,,"NDISUIO.Remove"
; Context help HKR,Ndi,HelpText,,%NDISUIO_HELP%
[NDISUIO.Install] AddReg=NDISUIO.AddReg DelReg=NDISUIO.Ins.DelReg CopyFiles=NDISUIO.CopyFiles
[NDISUIO.AddReg] HKR,,DevLoader,,*ndis,*ntkern HKR,,DeviceVxDs,,"ndisuio.sys"
[NDISUIO.CopyFiles] ndisuio.sys
[NDISUIO.Remove] DelReg=NDISUIO.Rmv.DelReg DelFiles=NDISUIO.CopyFiles
[NDISUIO.Rmv.DelReg]
;*************************************************************************** ; Destination Directories ;***************************************************************************
[DestinationDirs] NDISUIO.CopyFiles = 11 ; LDID_SYS
[SourceDisksNames]
[SourceDisksFiles]
;*************************************************************************** ; Localizable Strings ;***************************************************************************
[strings] V_MS="Microsoft" V_CLASSNAME="Network Protocol"
; Devices NDISUIO.DeviceDesc="Sample NDISUIO Protocol Driver"
; Parameters PARAM_YES="Yes" PARAM_NO="No" PARAM_OFF="Off" PARAM_NONE="None"
; Context help NDISUIO_HELP="Sample Protocol Driver"
WHICH DDK
See the Windows 2000 DDK.
Do not use the Windows 98 DDK for writing .SYS drivers. You will only require the Windows 98 DDK for programmatic installation (IPNEW), custom NDI procedures (MyNDI) and for the kernel debugger (WDEB98/RTERM).
Do not use the Windows XP DDK if you are developing .SYS drivers for Windows
2000 or Windows 9x/ME.
UNSUPPORTED FUNCTIONS/CODE=2
Some NDIS/Operating System functions are not supported in Windows 9x/Me and will prevent your driver from loading. The System Information will report Code=2. To determine the function that is causing this failure, load the debug version of VxDLDR.VxD to the Windows\System\Vmm32 folder. It will emit debug spew to the kernel debug console with a message similar to “PELDR: MyDriver.sys can’t find export <function> in module <ndis>.” You will have to find alternatives for any functions that are not supported.
NDIS VERSIONS
Be careful to properly match the NDIS version with the target operating system. The NDIS version for each OS is as follows:
| Windows 95: NDIS v 3.10 |
| Windows 98 FE: NDIS v 5.0 |
| Windows 98 SE: NDIS v 5.0 |
| Windows ME: NDIS v 5.0 |
| Windows 2000: NDIS 5.0 |
| Windows XP: NDIS 5.1 |
Specify the required version number in your SOURCES file with an appropriate –DNDISxx declare.
Also remember to set the proper version number in structures that require versioning, like ProtocolCharacteristics. Page faults will most likely occur if a higher version is passed in characteristic structures than that which is defined in the SOURCES file.
BINARY_COMPATIBLE/FUNCTIONS v MACROS
Always define BINARY_COMPATIBLE when building drivers for Windows 9x/Me.
Many NDIS functions are implemented as macros in Windows 2000 and XP. See the declaration of NdisSend and NdisRequest, both as a macro declaration and as a function prototype.
Failure to do so will yield unpredictable results. But most likely, a page fault will occur as your driver will jump to a random instruction in memory.
Behind the scenes, the BindingHandle that NidsOpenAdapter returns contains pointers directly to the miniport’s handlers, bypassing intermediate calls into NDIS. This is not supported in Windows 9x/ME.
STRINGS/ANSI v UNICODE
Functions that use strings, like NdisOpenAdapter and a protocol’s BindAdapterHandler will use UNICODE strings in Windows 2000/XP and ANSI strings in Windows 9x/ME. The DDK will always assume UNICODE strings, so actual manipulation of strings in 9x/Me will require special handling.
A protocol’s BindAdapterHandler contains a pointer to the adapter’s name, which it generally passes down to NdisOpenAdapter untouched. This is acceptable in 9x/Me because the contents of the string is never manipulated. However, in the NDISUIO XP DDK sample, the string is stored as UNICODE for later use. In the 9x/ME version of NDISUIO, either the copied string must be converted and stored in UNICODE or the driver and corresponding console application must be modified to pass ANSI strings throughout.
IM DRIVERS/INF
Windows 2000/XP intermediate drivers (PASSTHRU/MUX) install using two .INF files, one for the miniport edge and one for the protocol edge. The protocol edge installs as a Class=NetTrans. The miniport edge either installs as a Class=Net (MUX) or as a Class=NetService (PASSTHRU).
Windows 98/ME Intermediate Drivers install using a single .INF file and both edges are stamped as Class=NetTrans. The real class type of the miniport edge is declared in the special registry entry, “HKR,,RealClass,,Net”.
IM DRIVERS/INF/INSTALL PROBLEMS
The file NETLANE.INF in the Windows\Inf folder has been used as a starting point for installing Windows 9x/ME intermediate drivers. It installs ATMLANE.SYS, the ATM LAN Emulation driver.
Whereas the ATMLANE example installs cleanly, modifying this sample INF file doesn’t resolve other problems encountered in installing IM drivers in 9x/ME. ATMLANE’s upper and lower bindings are NDISATM and ATMLANE. In both cases, there’s only one binding partner (TCPIP exports NDISATM as its lower edge as well as Ndis3, Ndis4, Ndis5).
IM DRIVERS/FIREWALLS
Some third-party firewall products find miniports by walking through the HKLM\Enum registry hive mining for Class=Net devices. Because the miniport edge of IM drivers in Windows 98/ME is exposed as Class=NetTrans (see IM DRIVERS/INF, above), these firewalls will not notice your miniport. This is a poor design by these developers and there is no known solution for this situation.
IM DRIVERS/WIN95
Windows 95 does not support NdisIMInitializeDeviceInstance, whuch is a critical function for the protocol edge to make its internal binding to the miniport edge of your driver. Porting PASSTHRU to Windows 95, therefore, is not possible.
Protocol drivers and miniport drivers, on the other hand, is possible.
INF DIFFERENCES
Windows 2000/XP .INF files contain sections to install services, which include entries for Start, Group, ErrorControl and Type. Services are not used in Windows 9x/ME. Instead, DevLoader and DeviceVxDs entries must be created.
Sample Windows 2000/XP INF section:
[Install.Service]
AddService=MyDriver,,MYDRIVER_Service_Inst
[MYDRIVER_Service_Inst]
DisplayName = %MYDRIVER_Desc%
ServiceType = 1 ;SERVICE_KERNEL_DRIVER
StartType = 2 ;SERVICE_AUTO_START
ErrorControl = 1 ;SERVICE_ERROR_NORMAL
ServiceBinary = %12%\packet.sys
LoadOrderGroup = "PNP_TDI"
AddReg = AddReg_MYDRIVER_Service_Inst
Description = %MYDRIVER_Desc%
Sample Windows 9x/ME INF section:
AddReg=MYDRIVER.AddReg
[MYDRIVER.AddReg]
HKR,,DevLoader,,"*ndis,*ntkern"
HKR,,DeviceVxDs,,"MYDRIVER.sys"
Mine the Windows\Inf folder for sample .INF files.
DEBUGING/WIN98
The kernel debugger for Windows 98 and Windows 98 SE is contained in the Windows 98 DDK. On the target system, copy the program WDEB98.EXE to the Windows\System folder. In that system’s AUTOEXEC.BAT, add:
CD \WINDOWS\SYSTEM
WDEB98 /b /c:1 /r=9600 ..\WIN.COM
/b will cause the system to break when VMM32 starts, this gives a good opportunity to load other symbols (NDIS) and set break points
/c and /r select the com port and its rate.
.\WIN.COM causes Windows to be executed
On the debug console, run RTERM98. In Settings|Options, be sure to set an appropriate symbol search path and communications setting.
When the debugger is at a break point (i.e., VMM32 breaks due to /b, above), use ‘?’ for additional help.
Documentation can be found in the Windows 98 DDK in the Help folder. Launch Other.Chm and expand Related Driver Documentation\Windows 95 Documentation\Programmer’s Guide\WDEB386 System Debugger (WDEB98/RTERM98 was known as WDEB386/RTERM386 in the 95 documentation).
DEBUGING/WINME
Obtain the Windows ME Debug Kit at http://www.microsoft.com/ddk/debugging. Download the Microsoft Debugging Tools for Windows Me. Copy the executable to the target machine, launch, and follow the on screen instructions. Copy the binary RTERM.EXE to the debug console.
DEBUG BINARIES/SYMBOLS/WIN9X
The checked binaries for Windows 98 and Windows 98 SE can be found on the MSDN CD labeled “Windows 98 Other Versions.”
DEBUG BINARIES/SYMBOLS/WINME
Debug/checked NDIS binaries were not distributed. They can be downloaded via Knowledgebase article Q241517. Also view Knowledgebase article Q279356 for tips on using the debug version of NDIS.VxD.
SYSTEM FILE PROTECTION (SFP)/WINME
Follow the instructions in Q279356 (NDIS Debugging Tips for Windows ME) carefully. You must disable SFP before replacing any system files in Windows ME, including NDIS.VxD. Either boot up in safe mode (use F5 when starting Windows) or boot off of a Windows ME startup disk.
Also be aware that anytime you exit Network Neighborhood properties, the original “free” version of NDIS.VxD may be re-installed. The checked version will be over 300K.
NDIS_BUFFER
Never touch the elements of NDIS_BUFFER directly. This structure is vastly different between Windows 98/ME and Windows 2000/XP (where it’s a MDL).
Use the NDIS functions to access NDIS_BUFFER elements and treat that structure as completely opaque. Use NdisQueryBuffer, for example, to obtain a pointer to the buffer’s data.
RESOURCES
Q248413 [Win2K]
INFO: NDIS Debug Tracing and Kernel Debugger Extensions
Q266403 [Win2K]
HOWTO: Enable and Use NDIS Verifier
Q232515 [Win9x]
INFO: NDIS Level and Component Debugging Flags
Q279356 [WinME]
HOWTO: NDIS Debugging Tips for Windows ME
Q198582 [Win2K/Win9x/WinME]
INFO: NDIS Binary-Compatibility on Windows 98 and Windows 2K
Q224784 [Win2K/Win9x/WinME]
HOWTO: Writing WDM/NDIS Miniports for Windows
Q241517 [WinME]
SAMPLE: Ndis.exe Windows ME NDIS Debug Binaries
Q280063 [WinME]
DOC: MillinniumPreferred Directive Added to Net Class INF
Q282757 [WinME]
HOWTO: Use Network Setup Debug Extensions to NetDI for WinME
Q282778 [WinME]
INFO: Setting LowerRange for NDIS Protocol Drivers in WinME
Q285676 [WinME]
TCPIP Packets Discarded via Dial-up NDIS Intermed. Drivers
Visual C v 1.52c:
MSDN Platform Archive package, Disk 3, “16-bit DDKs”
|
Topic Status |
|
| December 3. 2003 | Information posted. |
|
PCAUSA Home
· Privacy Statement ·
Products · Ordering · Support ·
Utilities ·
Resources
|
NOTE: NDISUIO has been renamed
to NDISPROT in the latest Windows 2003 version of the DDK. See the topic
