NDIS binary compatibility on Windows 98 and on Windows 2000 (198582)

MORE INFORMATION

• 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:
  "PELDR: mydriver.sys can't find export NdisMRegisterUnloadHandler in module NDIS.SYS."
• 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 separate .inf files, or by using a multi-platform .inf file. Compare the .inf files for the packet driver in both the Microsoft Windows 98 DDK and the Microsoft Windows 2000 DDK:
  
  Windows 98
  
  From Win98ddk\Src\Net\Ndis3\Packet\Vxd\Vpacket.inf:

  AddReg=VPACKET.AddReg
  
  [VPACKET.AddReg]
  HKR,,DevLoader,,"*ndis,*ntkern"
  HKR,,DeviceVxDs,,"vpacket.sys"
  
  Note This example was altered from the actual vpacket.inf to illustrate the installation of a .sys driver.
  

  Windows 2000
  
  From Win2Kddk\Src\Network\Ndis\Packet\Packet.inf:
  
  

  [Install.Service]
  AddService=Packet,,PACKET_Service_Inst
  
  [Packet_Service_Inst]
  DisplayName = %PACKET_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_PACKET_Service_Inst
  Description = %PACKET_Desc%
  

• 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->Length = (strlen(_S)) * sizeof(WCHAR);\ 
      _D->MaximumLength = _D->Length + sizeof(WCHAR);\ 
      NdisAllocateMemory((PVOID *)&(_D->Buffer), _D->MaximumLength, 0, (-1));\ 
      _P = _D->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.