UMDF Driver Skeleton Sample

https://msdn.microsoft.com/zh-cn/library/ff561263(v=vs.85).aspx

UMDF Driver Skeleton Sample

SUMMARY

This sample demonstrates how to use the User-Mode Driver Framework to write a minimal driver and shows best practices. The Skeleton driver will successfully load on a device (either root enumerated or a real hardware device) but has the minimum PnP functionality and does not support any I/O operations.

The Skeleton driver is a template from which many of the other UMDF sample drivers were constructed. It is intended to serve as a starting point for other UMDF drivers that you may write.

BUILDING THE SAMPLE

Start a build environment window and change to the directory containing the sample driver source code.

Run build -ceZ, or use the macro BLD. This command invokes the Microsoft make routines to build the components. If the build succeeds, you will find the driver, UMDFSkeleton.dll in the binary output directory specified for the build environment. You can get the output path from the buildxxx.log file (for example buildfre_win7_x86.log). If it fails you can find errors and warnings in the build error (.err) and warning (.wrn) log files respectively (for example buildfre_wlh_x86.err).

INSTALLATION

The Skeleton sample provides two different INF files UMDFSkeleton_Root.inf and UMDFSkeleton_OSR.inf

UMDFSkeleton_Root.inf allows for the driver to be installed on a root-enumerated device:

To install the Skeleton driver:

1. Copy the driver binary and the UMDFSkeleton_Root.inf file to a directory on your test machine (for example c:\skeletonSample.)

2. Copy the UMDF coinstaller WUDFUpdate_MMmmm.dll (for example WUDFUpdate_01009.dll) from <WDK root dir>\<bld>\redist\wdf\<arch> to the same directory (for example c:\skeletonSample).

3. Change to the directory containing the inf and binaries (for example cd /d c:\skeletonSample.)

4. Next run devcon.exe as follows:

   devcon.exe install UMDFSkeleton_Root.inf UMDFSamples\Skeleton

   DevCon can be found in the tools directory of your WDK enlistment (for example: d:\winddk\<bld>\tools\devcon\i386\devcon.exe.)

To update the Skeleton driver after making any changes:

1. Increment the version number found in the INF. While this is not strictly necessary, it will help ensure PnP selects your new driver as a better match for the device.

2. Copy the updated driver binary and the UMDFSkeleton_Root.inf file to a directory on your test machine (for example c:\skeletonSample.)

3. Change to the directory containing the inf and binaries (for example cd /d c:\skeletonSample.)

4. Next run devcon.exe as follows:

   devcon.exe update UMDFSkeleton_Root.inf UMDFSamples\Skeleton

UMDFSkeleton_OSR.inf allows you to install the driver on the OSR USB-FX2 Learning Kit board from OSR:

Note This version of the sample requires installation of WinUsb runtime on Windows XP and would not work without that. The WinUsb co-installer will install WinUsb during your driver's installation and can be found in the \winddk\<bld>\redist\winusb\<arch> directory.

To install the Skeleton driver on the OSR USB-FX2 Learning Kit board do the following-

1. Copy the driver binary, the UMDF coinstaller (WUDFUpdate_MMmmm.dll - for example WUDFUpdate_01009.dll), the KMDF coinstaller (WdfCoinstallerMMmmm.dll - for example WdfCoinstaller01009.dll), the WinUSB coinstaller (WinUSBCoinstaller2.dll) and the UMDFSkeleton_OSR.inf file to a directory on your test machine (for example c:\skeletonSample). The KMDF coinstaller can be found in the \winddk\<bld>\redist\wdf\<arch>directory and the WinUSB coinstaller can be found in the \winddk\<bld>\redist\winusb\<arch> directory.

2. Attach the OSR USB-FX2 device to your computer.

3. The rest of the steps depend on the operating system that you are using -
   • On Windows 7 and later operating systems:
     • Launch Device Manager by executing command devmgmt.msc in a command window, or from Hardware and Sound program group in Control Panel.
     • Select OSR USB-FX2 device from Other Devices category and click Update Driver Software... from right-click menu.
     • Select Browse my computer for software and provide the location of the driver files.
     • Select Install this driver software anyway when the Windows Security dialog box appears.
     • After the driver is installed, you should see the device in Device Manager.
   • On Windows Vista and Windows Server 2008:
     • In the Found New Hardware dialog box, select Locate and install driver software (recommended).
     • Select Don't search online.
     • Select I don't have the disc. Show me other options.
     • Select Browse my computer for driver software (advanced).
     • Enter the location of the driver files, and select Install this driver software anyway when the Windows Security dialog box appears. After the driver is installed, you should see the device in Device Manager.
   • On Windows Server 2003 and Windows XP:
     • In the Found New Hardware Wizard dialog box, select Install from a list of specific location (Advanced).
     • Select Search the best driver in these locations, select Include this location in the search path, and then specify the location of the driver files. The system will scan the directory and pick up the matching INF file and start the installation.
     • When you receive a Hardware Installation Warning dialog box that states that your driver has not passed Windows Logo Testing, click Continue Anyway. The system will copy the driver and INF file, load the driver, and start the device.
     • When you see the Completing the Found New Hardware Wizard page, click Finish. The installation is complete. You should be able to see the device in Device Manager.

Alternately you may use DevCon to install the Skeleton driver for the OSR USB-FX2 device:

1. Copy the driver binary, the UMDF coinstaller, the KMDF coinstaller, the WinUSB coinstaller and the UMDFSkeleton_OSR.inf file to a directory on your test machine (for example c:\skeletonSample).

2. Attach the OSR USB-FX2 device to your computer.

3. On operating systems older than Windows 7, the "Found New Hardware" wizard should be displayed. Click Cancel.

4. Change to the directory containing the inf and binaries (for example cd /d c:\skeletonSample.)

5. Run devcon.exe as follows:

   devcon.exe update UMDFSkeleton_OSR.inf "USB\Vid_0547&Pid_1002"

   (note: the quotes are important because of the &)

   DevCon can be found in the tools directory of your WDK enlistment (for example: d:\winddk\<bld>\tools\devcon\i386\devcon.exe.)

To update the Skeleton driver after making any changes:

1. Increment the version number found in the INF. While this is not strictly necessary, it will help ensure PnP selects your new driver as a better match for the device.

2. Copy the updated driver binary, the UMDF coinstaller, the KMDF coinstaller, the WinUSB coinstaller and the UMDFSkeleton_OSR.inf file to a directory on your test machine (for example c:\skeletonSample).

3. Change to the directory containing the inf and binaries (for example cd /d c:\skeletonSample.)

4. Next run devcon.exe as follows:

   devcon.exe update UMDFSkeleton_OSR.inf "USB\Vid_0547&Pid_1002"

Code Tour

File Manifest

File			Description
Skeleton.htm	Documentation for this sample (this file).
comsup.cpp & comsup.h	COM Support code - specifically base classes which provide implementations for the standard COM interfaces IUnknown and IClassFactory which are used throughout the skeleton sample. The implementation of IClassFactory is designed to create instances of the CMyDriver class. If you should change the name of your base driver class, you would also need to modify this file.
dllsup.cpp	DLL Support code - provides the DLL's entry point as well as the single required export (DllGetClassObject). These depend on comsup.cpp to perform the necessary class creation.
exports.def	This file lists the functions that the driver DLL exports.
makefile	This file redirects to the real makefile, which is shared by all the driver components of the Windows Driver Kit.
internal.h	This is the main header file for the skeleton driver.
driver.cpp & driver.h	Definition and implementation of the driver callback class for the Skeleton sample.
device.cpp & driver.h	Definition and implementation of the device callback class for the Skeleton sample.
skeleton.rc	This file defines resource information for the Skeleton sample driver.
sources	Generic file that lists source files and all the build options
UMDFSkeleton_OSR.inx	File for installing the Skeleton driver to control the OSR USB-FX2 Learning Kit device. The build process converts this into an INF file.
UMDFSkeleton_Root.inx	File for installing the Skeleton driver to control a root enumerated device with a hardware ID of UMDFSamples\Skeleton. The build process converts this into an INF file.
Makefile.inc	A makefile that defines custom build actions. This includes the conversion of the .INX file into a .INF file.