Developing Drivers with the Windows Driver Foundation (Pro Developer)

UMDF and KMDF drivers are installed in exactly the same way-a user typically is not even aware of the difference. However, significant differences in the installation process for the two types of driver occur without the user being aware, controlled largely by the driver package's INF.

This section discusses examples of typical UMDF and KMDF co-installer sections from the INFs for Fx2_Driver and Osrusbfx2.

UMDF Example: The Fx2_Driver INF

The example in Listing 20-4 contains the co-installer sections from the Fx2_Driver INF created for an x86 build of the driver. The sections and important directives are summarized after the example.

Listing 20-4: Fx2_Driver INF co-installer sections

[OsrUsb_Install.NT] CopyFiles=UMDriverCopy Include=WINUSB.INF; Import sections from WINUSB.INF Needs=WINUSB.NT; Run the CopyFiles & AddReg directives for WinUsb.INF [OsrUsb_Install.NT.hw] AddReg=OsrUsb_Device_AddReg [OsrUsb_Install.NT.Services] AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall [OsrUsb_Install.NT.Wdf] KmdfService=WINUSB, WinUsb_Install UmdfDispatcher=WinUsb UmdfService=WUDFOsrUsbFx2, WUDFOsrUsbFx2_Install UmdfServiceOrder=WUDFOsrUsbFx2 [OsrUsb_Install.NT.CoInstallers] AddReg=CoInstallers_AddReg CopyFiles=CoInstallers_CopyFiles [WinUsb_Install] KmdfLibraryVersion = 1.5 [WUDFOsrUsbFx2_Install] UmdfLibraryVersion=1.5.0 DriverCLSID = "{}" ServiceBinary = "%12%\UMDF\WUDFOsrUsbFx2.dll" [OsrUsb_Device_AddReg] HKR,,"LowerFilters",0x00010008,"WinUsb" ; FLG_ADDREG_TYPE_MULTI_SZ | FLG_ADDREG_APPEND [WUDFRD_ServiceInstall] DisplayName = %WudfRdDisplayName% ServiceType = 1 StartType = 3 ErrorControl = 1 ServiceBinary = %12%\WUDFRd.sys LoadOrderGroup = Base [WinUsb_ServiceInstall] DisplayName = %WinUsb_SvcDesc% ServiceType = 1 StartType = 3 ErrorControl = 1 ServiceBinary = %12%\WinUSB.sys [CoInstallers_AddReg] HKR,,CoInstallers32,0x00010000,"WudfUpdate_01005.dll","WdfCoInstaller01005.dll, WdfCoInstaller","WinUsbCoinstaller.dll" [CoInstallers_CopyFiles] WudfUpdate_01005.dll WdfCoInstaller01005.dll WinUsbCoinstaller.dll [DestinationDirs] UMDriverCopy=12,UMDF ; copy to driversMdf Coinstallers_CopyFiles=11 [UMDriverCopy] WUDFOsrUsbFx2.dll

This part of the INF has several sections. Most sections are used by all UMDF drivers, but several sections are related to installing the kernel-mode WinUSB service, which is required for UMDF USB drivers. Other types of drivers do not need those sections. The following list shows the key sections and their directives:

•  The key Fx2_Driver INF co-installer sections  [OsrUsb_Install.NT]

  The Include and Needs directives are required for installing the WinUSB component on Windows Vista systems. Windows XP systems ignore these directives.

• [OsrUsb_Install.NT.hw]

  The AddReg directive adds information to the registry, as specified by the [OsrUsb_Device_AddReg] section. This section specifies WinUSB as the lower filter driver for the device stack.

• [OsrUsb_Install.NT.Services]

  This section specifies the kernel-mode filter drivers that this device requires:

  • WUDFRd is the UMDF reflector and is required for all UMDF drivers. As discussed earlier in this chapter, WUDFRd can be installed as a service, an upper filter driver, or a lower filter driver. Because Fx2_Driver is a function driver, WUDFRd is installed as a service.

  • The WinUsb service is required for all UMDF USB drivers.

  The installation is based on the data in the WUDFRD_ServiceInstall and WinUsb_ServiceInstall sections, respectively.

• [OsrUsb_Install.NT.Wdf]

  This is the [DDInstall.WDF] section referred to earlier. It has several directives:

  • KmdfService installs WinUSB, a kernel-mode service that UMDF USB drivers use. Other types of driver might not be required to include this directive.

  • UmdfDispatcher is an optional directive that informs the framework where to send requests after the requests leave the device stack. Because Fx2_Driver is a USB driver, the INF must have this directive to ensure that I/O requests are sent to the WinUSB component.

  • UmdfService specifies WUDFOsrUsbFx2 as the service name and points to the [WUDFOsrUsbFx2_Install] section for the remaining directives.

  • UmdfServiceOrder specifies WUDFOsrUsbFx2 as the only driver. If this sample had any filter drivers, they would be listed here in load order, starting with the lowest filter driver.

• [OsrUsb_Install.NT.Coinstallers]

  This is the [DDinstall.Coinstallers] section referred to earlier. It has two directives:

  • The AddReg directive adds the required co-installer information to the registry, as specified by the [Coinstaller_AddReg] section.

  • The CopyFiles directive copies the three co-installer files specified in the [Coinstaller_CopyFiles] section to the folder specified in [DestinationDirs].

• [WinUsb_Install]

  This section specifies 1.5 as the major version number of the KMDF library. The WinUSB service uses this library.

• [WUDFOsrUsbFx2_Install]

  This section is a continuation of the UmdfService directive earlier in the INF. It has the following three directives:

  • UmdfLibraryVersion specifies version 1.5.0 of the UMDF libraries.

  • DriverCLSID specifies the CLSID of Fx2_Driver's driver callback object as {}.

  • ServiceBinary specifies that the driver binaries should be placed in the %windir%\System32\Drivers\UMDF folder. %12% is a standard ID for %windir%\System32\Drivers.

• [WUDFRD_ServiceInstall]

  This section contains the data for installing the reflector as a service. Other INFs that install WUDFRd as a service should use the same settings.

• [WinUsb_ServiceInstall]

  This section contains the data for installing the WinUSB service. Other INFs that install WinUSB should use exactly the same settings.

• [DestinationDirs]

  This section specifies the destination of the framework files. The value 12 is a standard ID for the %Windir%\System32\Drivers folder.

KMDF Example: The Osrusbfx2 INF

The example in Listing 20-5 shows the co-installer portion of the Osrusbfx2 INF. The sections and important directives are summarized after this example.

Listing 20-5: Osrusbfx2 INF co-installer sections

[DestinationDirs] Coinstaller_CopyFiles = 11 [osrusbfx2.Dev.NT.Coinstallers] AddReg=Coinstaller_AddReg CopyFiles=Coinstaller_CopyFiles [Coinstaller_CopyFiles] wdfcoinstaller01005.dll [SourceDisksFiles] wdfcoinstaller01005.dll=1 [Coinstaller_AddReg] HKR,,Coinstallers32,0x00010000, "wdfcoinstaller01005.dll,WdfCoinstaller" [osrusbfx2.Dev.NT.Wdf] KmdfService = osrusbfx2, osrusbfx2_wdfsect [osrusbfx2_wdfsect] KmdfLibraryVersion = 1.5

The following list describes the sections:

•  The key Osrusbfx2 INF co-installer sections  [DestinationDirs]

  This section specifies the destination of the framework files. The value 11 is a standard ID for the %windir%\System32 folder.

• [OsrUsbFx2.Dev.NT.Coinstallers]

  This section is the [DDInstall.Coinstallers] section mentioned earlier. It specifies the following two actions:

  • The AddReg directive adds information to the registry, as specified by the [Coinstaller_AddReg] section.

  • The CopyFiles directive copies the files in the [Coinstaller_CopyFiles] section to the folder specified in [DestinationDirs].

• [SourceDisksFiles]

  This section contains the name and location of the co-installer DLL- wdfcoinstaller01005.dll. The value 1 is defined at the beginning of the INF in [SourceDisksNames] and corresponds to the installation disk.

• [Osrusbfx2.Dev.NT.Wdf]

  This section was referred to earlier as [DDInstall.Wdf]. It assigns osrusbfx2 as the name of the driver's kernel-mode service.

• [Osrusbfx2_wdfsect]

  This section was referred to earlier as [Wdf-install]. It specifies version 1.5 of the KMDF libraries.