Microsoft KB Archive/198582

{|
 * width="100%"|

INFO: NDIS Binary-Compatibility on Windows 98 and Windows 2000

 * }

Q198582

-

The information in this article applies to:


 * Microsoft Windows 2000 Driver Development Kit (DDK)
 * Microsoft Windows 98 Driver Development Kit (DDK)

-

SUMMARY
There are several special considerations that a developer must observe to successfully ship a binary-compatible NDIS Miniport driver for Microsoft Windows 2000 and Microsoft Windows 98. The considerations are caused by differences in the implementation of NDIS and Windows Management Instrumentation (WMI) on these platforms.

MORE INFORMATION
Severe considerations:

 NdisMInitializeScatterGatherDma is implemented ONLY on the Windows 2000 version of NDIS. A binary-compatible miniport must restrict itself to the NDIS 4.0 DMA functions. Any miniport that uses NdisMInitializeScatterGatherDma fails to load on Windows 98 because of this unresolved external reference. Several NDIS and Microsoft Windows NT kernel functions are not supported in Microsoft Windows 95 or Microsoft Windows 98, and their use prevents your driver from loading. One particular example is NdisMRegisterUnloadHandler. A symptom of this problem includes:

  The expected debug output in your DriverEntry (that is, a banner message) never prints and the Microsoft System Information utility displays the following text:

"This device has a problem: Code=2 (0x2)"



An easy method you can use to identify these functions is to copy the checked build of the Vxdldr.vxd (the VxD loader) file to the \Windows\System\VMM32 folder of a test Windows 95 or Windows 98 computer. Vxdldr outputs the failure. Using the earlier NdisMRegisterUnloadHandler example, the error is: There are several important differences in the driver's installation .inf file. Whereas Windows NT-style drivers require service entries for Start, Group, Type and ErrorControl, the same driver in Windows 95 or Windows 98 requires entries for DeviceVxDs and DeviceLoader. You can accomplish this by shipping seperate .inf files, or by using a multi-platform .inf file.

Benign considerations:

Wake-On-Lan is fully implemented only on the Windows 2000 platform. A binary-compatible miniport could implement Wake-On-Lan; however, the driver should gracefully handle any situations on Windows 98 where these functions do not perform their intended actions.

TCP/IP task offload is fully implemented only on Windows 2000. A binary-compatible miniport correctly supports these tasks on Windows 2000 and will gracefully work on Windows 98 even though these tasks are never requested.

The NdisMxxxLog functions are implemented only on Windows 2000. You must use these functions in the debug version of a miniport; no retail builds of an NDIS miniport use these functions. A driver that includes references to these functions loads on Windows 98; however, these functions do not perform their intended actions. For example, NdisMCreateLog returns NDIS_STATUS_SUCCESS; however, the loghandle is undefined. The NdisMxxxLog functions are:


 * NdisMCreateLog
 * NdisMCloseLog
 * NdisMWriteLogData
 * NdisMFlushLog

The driver must be designed to operate independent of WMI and independent of when OID_GEN_SUPPORTED_GUIDS is requested. On Windows 2000, a miniport driver can expect its QueryInformationHandler to receive an OID_GEN_SUPPORTED_GUIDS request during initialization because Windows NT Tools exist that register with WMI to obtain a wide variety of system information. However, on Windows 98 the miniport receives this request only when a WMI client specifically requests information. This may happen during initialization or later during a network session.

NdisInitializeString is implemented only on Windows 2000. A miniport that uses NdisInitializeString fails to load on Windows 98. A binary compatible miniport uses the following macro instead:

#define NdisInitializeString(Destination,Source) \ {\    PNDIS_STRING _D = (Destination);\ UCHAR *_S = (Source);\ WCHAR *_P;\ _D-&gt;Length = (strlen(_S)) * sizeof(WCHAR);\ _D-&gt;MaximumLength = _D-&gt;Length + sizeof(WCHAR);\ NdisAllocateMemory((PVOID *)&(_D-&gt;Buffer), _D-&gt;MaximumLength, 0, (-1));\ _P = _D-&gt;Buffer;\ while(*_S != '\0'){\ *_P = (WCHAR)(*_S);\ _S++;\ _P++;\ }\    *_P = UNICODE_NULL;\ } Windows 98 co-installers, if necessary, must be written by using the 16-bit 1.52c compiler. The network class installer (NetDI.dll) and the Windows Setup Functions (Setupx.dll) are both 16-bit DLLs. Review the Network Device Installer (MyNDI) and IPNEW examples in the Windows 98 DDK.

Intermediate drivers: Due to differences between Windows 98 and Windows 2000 architecture, writing binary-compatible NDIS Intermediate Drivers is not recommended. Doing so prevents you from adopting new NDIS features. Nevertheless, a high degree source-compatibility can be achieved with minimal #ifdefs to mask out differences. A summary of these differences follows:


 * Windows 2000 uses the NDIS function NdisMRegisterUnloadHandler. NdisMRegisterUnloadHandler is not supported in Windows 98, and you must use ProtocolCharacteristics.UnloadHandler instead.
 * NdisIMCopySendPerPacketInfo is not supported in Windows 98 and must not be used.