Windows 7 : Programming Drivers for the User Mode Driver Framework - Required Driver Functionality, UMDF Sample Drivers

9/26/2012 1:48:07 AM

1. Required Driver Functionality

Every UMDF driver must provide the following functionality:

  • Support the DllMain export as its primary entry point.

    The driver must support DllMain as its primary entry point. After the system creates the UMDF driver host process, the host process loads the driver by calling the DllMain function. In a UMDF driver, this function does very little; typically, it enables tracing and then returns. As in all DLLs, the driver must not make blocking calls such as WaitForSingleObject, which can deadlock the system. Drivers should defer resource allocation to IDriverEntry::OnInitialize, instead of DllMain.

  • Support the DllGetClassObject export, which must return a pointer to an IClassFactory interface that creates an instance of the driver callback object.

    The driver must also support the DllGetClassObject function, which COM requires. This function returns a pointer to an IClassFactory interface with which UMDF can create an instance of the driver callback object. The UMDF sample drivers show how to implement this function. Alternatively, the Active Template Library (ATL) wizard can be used to generate the supporting COM code.

  • Implement the IDriverEntry interface on the driver class.

    Finally, every User Mode WDF driver must implement the IDriverEntry interface on the driver class. This interface includes methods that initialize and uninitialize driver-wide data. UMDF calls the OnInitialize method when the first device for the driver is loaded and calls the OnDeinitialize method when the driver is unloaded. IDriverEntry also includes the OnAddDevice method, which UMDF calls when the Plug and Play manager enumerates one of the driver’s devices.

Figure 1 shows the interactions of the functionality of a driver with UMDF and the system.

Figure 1. Flow of Control for UMDF and Driver

When the system starts, the driver manager is loaded and the following actions occur:

  1. The driver manager creates the driver host process and then loads the driver library by calling the DllMain entry point. DllMain performs any required global initialization for the driver, such as starting tracing.

  2. UMDF creates a framework driver object and calls the driver at DllGetClassObject to get an interface that I can use to create a corresponding callback object in the driver. DllGetClassObject returns a pointer to the driver’s IClassFactory interface.

  3. UMDF calls the CreateInstance method of the IClassFactory interface to create an instance of the driver callback object. The driver callback object implements methods to initialize the driver, to notify it that one of its devices has been enumerated, and to prepare it for unloading.

  4. UMDF calls the OnInitialize method of the driver callback object to initialize the driver.

  5. Whenever one of the driver’s devices is enumerated, UMDF calls OnDeviceAdd. OnDeviceAdd performs any required configuration, creates a device callback object to represent the device, creates any required device interfaces, and creates and configures the queues into which UMDF will place I/O requests that are targeted at the driver. A device interface is a device feature that driver exposes to applications or other system components, whereas a COM interface is a related group of functions that act on an object.

  6. UMDF queries for the Plug and Play and queue interfaces that it will use to handle I/O requests.

  7. When the device is removed, UMDF calls the Plug and Play methods that are appropriate for the type of removal (orderly or surprise), deletes the objects, and calls the IDriverEntry::OnDeinitialize method to clean up. It then unloads the DLL and deletes the driver host process.

2. UMDF Sample Drivers

The UMDF release for Windows 7 includes several sample User Mode Drivers, which are installed at WDF\UMDF\src in the Windows Driver Kit (WDK) installation directory. You can use these samples as the basis for your own driver. Table 1 lists the UMDF samples.

Table 1. List of UMDF Sample Drivers
SkeletonMinimal software-only driver that shows the structure and fundamental components of a simple UMDF driver.
EchoSimple driver that uses a serial I/O queue and handles one I/O request at a time. The Echo sample defers the completion of each I/O request to a worker thread and shows how to mark a request cancelable while it is pending in the driver. This sample was adapted from the KMDF Echo sample and is functionally similar to the WDM sample of the same name.
USB\DriverHardware driver for the USB-FX2 Learning Kit from OSR. This sample supports a parallel I/O queue. It is similar to the Echo sample, but can handle multiple independent requests at one time. This driver also demonstrates how a User Mode Driver controls a device. It uses the memory in the OSR-USBFx2 device as a buffer and uses the WinUSB API and WinUSB Kernel Mode Driver to control the hardware. The driver demonstrates how to escape from UMDF and send I/O by using an alternate path and how to synchronize I/O on the alternate path with cancellation and file closure.
USB\FilterFilter driver for the WinUSB driver stack. This sample modifies the data in read and write requests as they flow through the device stack and uses I/O targets to communicate with a lower driver.

Use the WDK build environment to build the samples. To build a particular sample:

Start a build environment window.

Set the working directory to the directory that contains the sample to build.

Type the following command: build –ceZ

2.1. Minimal UMDF Driver: The Skeleton Driver

The Skeleton driver contains the minimum amount of code that is required in a loadable UMDF driver. It was designed as a starting point from which to build drivers for actual hardware. In addition to demonstrating the minimal required features and best practices, the Skeleton driver splits into appropriate modules the common code that is required in all UMDF drivers.

The Skeleton driver supports a driver entry point, functions to create and initialize the driver and device callback objects, and functions for COM support. It does not support any I/O or Plug and Play operations. Table 2 lists the component source files.

Table 2. Component Source Files
Comsup.cppSource code for the CUnknown and CClassFactory classes.
Comsup.hHeader file for COM support functions and classes.
Device.cppSource code for the device callback object class, CMyDevice.
Device.hHeader file for the device callback object.
Dllsup.cppSource code for the driver entry point and exported COM support functions.
Driver.cppSource code for the driver callback object class, CMyDriver.
Driver.hHeader file for the driver callback object.
Exports.defDefinition file that identifies the library name and exported entry point for driver.
Internal.hHeader file for local type definitions.
MakefileGeneric makefile for building the sample.
Makefile.incAdditional commands input to the makefile.
Skeleton.htmHelp file that describes the sample.
Skeleton.rcResource file for the sample.
SourcesSource file for the build procedure.
UMDF_Skeleton_OSR.inxINF that installs the Skeleton sample as a driver for the OSR USBFX2 device.
UMDF_Skeleton_OSR_xp.inxINF that installs the Skeleton sample as a driver for the OSR USBFX2 device on Windows 7.
UMDF_Skeleton_root.inxINF that installs the Skeleton sample as a driver for a root-enumerated device.
UMDF_Skeleton_root_xp.inxINF that installs the Skeleton sample as a driver for a root-enumerated device on Windows 7.

2.2. Skeleton Driver Classes, Objects, and Interfaces

The Skeleton driver implements the four classes that are listed in Table 3.

Table 3. Classes Implemented in Skeleton Driver
Class NameDescriptionPublic Interfaces
CUnknownBase Class from which others deriveIUnknown
CClassFactoryClass factory that instantiates the driver classIClassFactory
CMyDriverDriver callback object classIDriverEntry IUnknown
CMyDeviceDevice callback objectIUnknown

Figure 2 shows how the objects that are instantiated from these classes interact with the corresponding framework objects.

Figure 2. Interaction of Framework and Skeleton Objects

As Figure 2 shows, the framework implements a driver object and a device object. The framework’s driver object uses the IDriverEntry interface on the Skeleton driver’s CMyDriver object, and the CMyDriver object, in turn, uses the IWdfDriver interface on the framework’s driver object. The framework’s device object exposes the IWdfDevice and IWdfDeviceInitialize interfaces, which the driver’s CMyDevice object uses. The Skeleton driver’s CMyDevice class does not implement additional interfaces because it does not support hardware or handle I/O requests. The device object in a typical driver would implement additional interfaces for Plug and Play notifications, I/O requests, I/O queues, and so forth.

Top 10
Review : Sigma 24mm f/1.4 DG HSM Art
Review : Canon EF11-24mm f/4L USM
Review : Creative Sound Blaster Roar 2
Review : Philips Fidelio M2L
Review : Alienware 17 - Dell's Alienware laptops
Review Smartwatch : Wellograph
Review : Xiaomi Redmi 2
Extending LINQ to Objects : Writing a Single Element Operator (part 2) - Building the RandomElement Operator
Extending LINQ to Objects : Writing a Single Element Operator (part 1) - Building Our Own Last Operator
3 Tips for Maintaining Your Cell Phone Battery (part 2) - Discharge Smart, Use Smart
- First look: Apple Watch

- 3 Tips for Maintaining Your Cell Phone Battery (part 1)

- 3 Tips for Maintaining Your Cell Phone Battery (part 2)
- How to create your first Swimlane Diagram or Cross-Functional Flowchart Diagram by using Microsoft Visio 2010 (Part 1)

- How to create your first Swimlane Diagram or Cross-Functional Flowchart Diagram by using Microsoft Visio 2010 (Part 2)

- How to create your first Swimlane Diagram or Cross-Functional Flowchart Diagram by using Microsoft Visio 2010 (Part 3)
Popular Tags
Microsoft Access Microsoft Excel Microsoft OneNote Microsoft PowerPoint Microsoft Project Microsoft Visio Microsoft Word Active Directory Biztalk Exchange Server Microsoft LynC Server Microsoft Dynamic Sharepoint Sql Server Windows Server 2008 Windows Server 2012 Windows 7 Windows 8 Adobe Indesign Adobe Flash Professional Dreamweaver Adobe Illustrator Adobe After Effects Adobe Photoshop Adobe Fireworks Adobe Flash Catalyst Corel Painter X CorelDRAW X5 CorelDraw 10 QuarkXPress 8 windows Phone 7 windows Phone 8
Visit movie_stars's profile on Pinterest.