How to Customize the Skeleton Sample Build and Installation Support Files

The Build utility uses the build support files to build the driver project. For most UMDF drivers, you can simply copy the Skeleton sample support files and modify them to suit the requirements of your driver.

Chapter 19, "How to Build WDF Drivers," and Chapter 20, "How to Install WDF Drivers," provide further discussion of these support files.

Sources

The Sources file contains a list of source files plus related information that the Build utility requires. You must modify several parts of this file, as shown in Listing 13-8.

Listing 13-8: The Skeleton sample Sources file

 #[1] UMDF_VERSION=1 UMDF_MINOR_VERSION=5 #[2] TARGETNAME=UMDFSkeleton TARGETTYPE=DYNLINK USE_MSVCRT=1 C_DEFINES = $(C_DEFINES)  /D_UNICODE /DUNICODE WIN32_WINNT_VERSION=$(LATEST_WIN32_WINNT_VERSION) _NT_TARGET_VERSION=$(_NT_TARGET_VERSION_WINXP) NTDDI_VERSION=$(LATEST_NTDDI_VERSION) DLLENTRY=_DllMainCRTStartup DLLDEF=exports.def #[3] SOURCES=\     Skeleton.rc                 \     dllsup.cpp                  \     comsup.cpp                  \     driver.cpp                  \     device.cpp #[4] TARGETLIBS=\         $(SDK_LIB_PATH)\strsafe.lib     \         $(SDK_LIB_PATH)\kernel32.lib    \         $(SDK_LIB_PATH)\advapi32.lib #[5] NTTARGETFILES=$(OBJ_PATH)\$(O)\UMDFSkeleton_Root.inf \               $(OBJ_PATH)\$(O)\UMDFSkeleton_OSR.inf MISCFILES=$(NTTARGETFILES) #[6] RUN_WPP= $(SOURCES) -dll -scan:internal.h 

Notes on the Skeleton sample Sources implementation in Listing 13-8:

1. This version of the Skeleton sample was implemented against UMDF version 1.5. If you use a later version of UMDF, change the version numbers accordingly.

2. TARGETNAME specifies the name of several output files, including the driver binary. Change this name to a suitable name for your driver.

3. SOURCES specifies the source files that are to be compiled. Modify names and add files, as necessary for your project.

4. TARGETLIBS specifies the static libraries that the driver links to. Modify this list as necessary for your project.

5. NTTARGETFILES indicates that the project includes a Makefile.inc file.

   In the Skeleton sample, Makefile.inc contains the instructions for creating an INF file from the project's INX file. The value assigned to NTTARGETFILES specifies the name of the INF file. You should change that to a suitable value for your driver.

    Note  The Skeleton sample produces two INFs: one to install the driver as a root-enumerated device and the other to install the Skeleton sample as a driver for the Fx2 device. Most projects require only a single INF to install the driver for the associated device.

6. RUN_WPP runs the WPP preprocessor. The final argument indicates that the Skeleton sample has a custom trace message function, which is defined in Internal.h. If you choose not to use a custom trace message or define it differently, you must delete or modify this argument.

Make Files

Makefile and Makefile.inc contain the directives for building the project. Use these make files as follows:

• Makefile should be the same for all driver projects.

  Use this file from the Skeleton sample without modification.

• Makefile.inc contains directives for creating an INF from the project's INX file. That code should be used without modification.

  If your project has additional custom targets, add the build directives to Makefile.inc.

Exports

Exports.def, as shown in Listing 13-9, specifies the functions that are to be exported by name from the DLL. The Skeleton sample exports one function: DllGetClassObject. This is typical for UMDF drivers, so most projects can use the Skeleton sample file with one minor modification: replace UMDFSkeleton.DLL with the name of your driver binary.

Listing 13-9: The Skeleton sample Exports.def file

 LIBRARY      "UMDFSkeleton.DLL" EXPORTS     DllGetClassObjectPRIVATE 

Version Resource File

Skeleton.rc contains driver version and identification information. You should change the file name and highlighted strings to appropriate values for your driver, as shown in Listing 13-10.

Listing 13-10: The Skeleton sample version resource file

 #include <windows.h> #include <ntverp.h> #define VER_FILETYPE                VFT_DLL #define VER_FILESUBTYPE             VFT_UNKNOWN #define VER_FILEDESCRIPTION_STR     "WDF:UMDF Skeleton User-Mode Driver Sample" #define VER_INTERNALNAME_STR        "UMDFSkeleton" #define VER_ORIGINALFILENAME_STR    "UMDFSkeleton.dll" #include "common.ver" 

INX File

The Build utility invokes Stampinf to create an INF from the INX. An INX file is almost identical to the corresponding INF file. The difference is that the INX contains several tokens that Stampinf replaces with the appropriate values for the build:

• $ARCH$ is replaced by the CPU architecture for which the driver is compiled.

• $UMDFVERSION$ is replaced by the correct UMDF version.

• $UMDFCOINSTALLERVERSION$ is replaced by the correct UMDF co-installer version.

To use the Skeleton sample INX file as a basis for your own driver's installation, you must modify several settings.

Chapter 20, "How to Install WDF Drivers," provides more information on INX and INF files.

The example in Listing 13-11 is from UMDFSkeleton_OSR.inx, which installs the Skeleton sample as a driver for the Fx2 device. UMDFSkeleton_Root.inx is not discussed here because relatively few drivers are installed as root-enumerated devices. UMDFSkeleton_Root.inx is similar to UMDFSkeleton_OSR.inx, but lacks a number of directives and values that device drivers require. Note that many of the strings in the file are defined at the end and inserted in the directives as %StringName%.

Listing 13-11: The Skeleton sample INX file

 ; [1] [Version] Signature="$Windows NT$" Class=Sample ClassGuid={} Provider=%MSFTUMDF% DriverVer=03/25/2005,0.0.0.1 CatalogFile=wudf.cat ; [2] [Manufacturer] %MSFTUMDF%=Microsoft,NT$ARCH$ ; [3] [Microsoft.NT$ARCH$] %SkeletonDeviceName%=Skeleton_Install, USB\Vid_045e&Pid_94aa&mi_00 %SkeletonDeviceName%=Skeleton_Install, USB\VID_0547&PID_1002 ; [4] [ClassInstall32] AddReg=SampleClass_RegistryAdd [SampleClass_RegistryAdd] HKR,,,,%ClassName% HKR,,Icon,,"-10" ; [5] [SourceDisksFiles] UMDFSkeleton.dll=1 WudfUpdate_$UMDFCOINSTALLERVERSION$.dll=1 WdfCoInstaller01005.dll=1 WinUsbCoinstaller.dll=1 ; [6] [SourceDisksNames] 1 = %MediaDescription% ; [7] [Skeleton_Install.NT] CopyFiles=UMDriverCopy Include=WINUSB.INF Needs=WINUSB.NT ; [8] [Skeleton_Install.NT.hw] AddReg=Skeleton_Device_AddReg ; [9] [Skeleton_Install.NT.Services] AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall [Skeleton_Install.NT.CoInstallers] CopyFiles=CoInstallers_CopyFiles AddReg=CoInstallers_AddReg ; [10] [Skeleton_Install.NT.Wdf] KmdfService = WINUSB, WinUsb_Install UmdfService = UMDFSkeleton, UMDFSkeleton_Install UmdfServiceOrder = UMDFSkeleton [WinUsb_Install] KmdfLibraryVersion = 1.5 [UMDFSkeleton_Install] UmdfLibraryVersion=$UMDFVERSION$ DriverCLS ServiceBinary="%12%\umdf\UMDFSkeleton.dll" [Skeleton_Device_AddReg] HKR,,"LowerFilters",0x00010008,"WinUsb" [WUDFRD_ServiceInstall] DisplayName = %WudfRdDisplayName% ServiceType = 1 StartType = 3 ErrorControl = 1 ServiceBinary = %12%\WUDFRd.sys LoadOrderGroup = Base ; [11] [WinUsb_ServiceInstall] DisplayName     = %WinUsb_SvcDesc% ServiceType     = 1 StartType       = 3 ErrorControl    = 1 ServiceBinary   = %12%\WinUSB.sys ; [12] [CoInstallers_AddReg] HKR,,CoInstallers32,0x00010000,"WudfUpdate_$UMDFCOINSTALLERVERSION$.dll", "WinUsbCoinstaller.dll", "WdfCoInstaller01005.dll,WdfCoInstaller" [CoInstallers_CopyFiles] WudfUpdate_$UMDFCOINSTALLERVERSION$.dll WdfCoInstaller01005.dll WinUsbCoinstaller.dll [DestinationDirs] CoInstallers_CopyFiles=11    ; copy to system32 UMDriverCopy=12,UMDF ; copy to drivers/umdf ; [13] [UMDriverCopy] UMDFSkeleton.dll ; [14] [Strings] MSFTUMDF="Microsoft Internal (WDF:UMDF)" MediaDescription="Microsoft Sample Driver Installation Media" ClassName="WUDF Sample" WudfRdDisplayName="Windows Driver Foundation - User-mode Driver Framework Reflector" SkeletonDeviceName="Microsoft Skeleton User-Mode Driver on OSR USB Device Sample" WinUsb_SvcDesc="WinUSB Driver" 

Notes on the Skeleton sample INX implementation in Listing 13-11:

1. In the [Version] section, change the values assigned to Class and ClassGuid to suitable values for your device. Change %MSFTUMDF% and the associated string to a suitable value for your driver.

    Tip  See "Device Setup Classes" in the WDK for more information on Class and ClassGuid values-online at http://go.microsoft.com/fwlink/?LinkId=80620.

2. In the [Manufacturer] section, replace %MSFTUMDF% with the new value. You should also change "Microsoft" to your company name.

3. In the [Microsoft.NT$ARCH$] section:

   • Change "Microsoft" in the section name to match the company name specified in the [Manufacturer] section.

   • Modify the string assigned to %SkeletonDeviceName% to an appropriate value for your device. This string specifies the DDInstall value that is used later in the file. Change all instances of "Skeleton_Install" later in the file to the specified string.

   • Change the hardware IDs to the values for your device.

4. In the [ClassInstall32] section, change %ClassName% in the associated [SampleClass_RegistryAdd] section to an appropriate value for your device.

5. In the [SourceDisksFiles] section:

   • Change UMDFSkeleton.dll to the name of your driver binary.

   • WinUsbCoinstaller.dll is the co-installer for WinUSB and is required only for USB drivers.

   • WdfCoInstaller01005.dll is the KMDF co-installer. It is included here because UMDF USB drivers depend on WinUSB, which is based on KMDF. If you are implementing a USB driver or another type of driver with components that depend on KMDF, keep this directive but update the version, if necessary. Otherwise, delete the directive.

6. In the [SourceDisksNames] section, change the string assigned to %MediaDescription% to an appropriate value for your driver.

7. Change Skeleton_InstalI in the following section names to the DDInstall value specified in step 3.

   The Include and Needs directives in [DDInstall.NT] are required for USB drivers. Otherwise, delete the directives.

8. This section and the associated [Skeleton_Device_AddReg] section install WinUSB as a lower filter driver for the Skeleton sample driver. It is required for USB drivers, and other types of drivers can use it for purposes such as installing a filter driver.

   If you are implementing a USB driver:

   • In the [Skeleton_Install.NT.hw] section, change Skeleton_Device_AddReg and the corresponding section name to an appropriate value for your driver.

   • Use the HKR directive in the [Skeleton_Device_AddReg] section without modification.

9. In the [DDInstall.NT.Services] section:

   • If your driver is a filter driver, change the [DDInstall.NT.Services] section to install the reflector-WUDFRd-as a filter driver in the kernel-mode device stack.

   • If your driver is a function driver, the [DDInstall.NT.Services] section should install the reflector as the service for the device.

   • If your driver is not a USB driver, delete the second AddService directive, which adds the WinUSB service.

    Note  The second element of the value specified by AddService is a flag field. The first bit of this field specifies whether the driver is a function driver or a filter driver.

    Tip  See "INF AddService Directive" on MSDN for more information on flag settings-online at http://go.microsoft.com/fwlink/?LinkId=81348.

10. In the [DDInstall.Wdf] section:

    • If you are implementing a USB driver, use the KmdfService directive and the associated [WinUsb_Install] section, but if necessary, change the KmdfLibraryVersion directive to the appropriate version. If you are implementing a non-USB driver that has a dependency on KMDF, modify the KmdfService directive as appropriate. Otherwise, delete the directive and the associated section.

    • Change the values assigned to the UmdfService directive values appropriate to your driver. Assign the driver name to the UMDFServiceOrder directive.

    • If your driver performs impersonation, add a UMDFImpersonation directive that specifies the maximum impersonation level for the driver.

    • In the associated [UMDFSkeleton_Install] section, change the name of the section to the value specified in the UmdfService directive. Change the ServiceBinary value to the name of your driver binary. Change the DriverCLSID value to the CLSID of your driver's driver callback object.

11. If you are implementing a USB driver, use [WinUsb_ServiceInstall] section without modification. Otherwise, delete the section.

12. The [CoInstallers_AddReg] and [CoInstallers_CopyFiles] sections are both referenced by the [DDInstall.NT.Coinstallers] sections:

    • If you are implementing a driver that depends on KMDF, update the version number for WdfCoInstaller01005.dll, if necessary.

    • If you are not implementing a USB driver, delete the WinUsbCoinstaller.dll value.

    • If you are not implementing a driver that depends on KMDF, delete the WdfCoInstaller01005.dll and WdfCoInstaller values.

13. In the [UMDriverCopy] section, change UMDFSkeleton.dll to the name of your driver binary.

14. In the [Strings] section, change the directives and values in this section to appropriate strings for your driver.

    Additional changes to the INX might be required, depending on the type of device that your driver supports or whether it's a software-only driver such as a filter driver.