Developing Drivers with the Windows Driver Foundation (Pro Developer)

KMDF defines a larger set of objects than UMDF defines, because kernel-mode drivers have access to additional resources and can perform certain operations, such as handling interrupts, that user-mode drivers cannot perform. In addition to the object types that UMDF supports, KMDF also includes the following types of objects:

KMDF does not support a named property store; instead, KMDF drivers manage persistent data by using registry key objects.

From the driver's perspective, WDF objects are opaque and the driver never directly accesses the underlying structure. Instead, a KMDF driver refers to an object by using a handle. The driver passes the handle as a parameter to the object's methods, and KMDF passes the handle as a parameter to event callbacks.

KMDF Object Types

For KMDF drivers, the framework creates objects for which the driver supplies callback function pointers. KMDF drivers do not require callback objects. Table 5-3 lists all of the KMDF object types.

 Note  Framework objects are unique to the framework. Framework objects are not managed by the Windows object manager and cannot be manipulated by using the system's ObXxx functions. Only the framework and its drivers can create and operate on framework objects. Framework objects are also unique to the driver that created them and should not be shared between two different framework drivers.

KMDF Naming Conventions

KMDF follows a set of naming conventions for the methods, properties, and events that its objects support.

 KMDF method names  KMDF methods are named:

• WdfObjectOperation

where:

• Object specifies the KMDF object on which the method operates.

• Operation indicates what the method does.

For example, the WdfDeviceCreate method creates a framework device object.

 KMDF property names  KMDF properties are named:

• WdfObject{Set|Get}Data

• WdfObject{Assign|Retrieve}Data

where:

• Object specifies the KMDF object on which the function operates.

• Data specifies the field that the function reads or writes.

Some properties can be read and written without failure, but other properties can sometimes fail. Functions with Set and Get in their names read and write fields without failure. The Set functions return VOID, and the Get functions typically return the value of the field. Functions with Assign and Retrieve in their names can fail and return an NTSTATUS value.

For example, the WDFINTERRUPT object represents the interrupt object for a device. Each interrupt object is described by a set of characteristics that indicate the type of interrupt-message signaled or IRQ based-and provide additional information about the interrupt. The WdfInterruptGetInfo method returns this information. A corresponding method to set the value is not available, because the driver initializes this information when it creates the object and cannot change it later.

 KMDF event callback function names  In header files and documentation, the placeholders for KMDF event callback functions are named:

• EvtObjectDescription

where:

• Object specifies the KMDF object on which the function operates.

• Description indicates what triggers the callback.

Most of the sample drivers name callback functions by replacing or prepending Evt with the name of the driver. For example, the Osrusbfx2 driver's callback function names typically start with OsrFxEvt. Conforming to a similar convention in your own drivers is a good idea, because it improves code readability and makes clear the purpose of each function, when it is called, and who calls it.

A driver registers callbacks only for the events that are important to its operation. When the event occurs, the framework invokes the callback, passing as a parameter a handle to the object for which the callback is registered. For example, if a device can be ejected, its driver registers an EvtDeviceEject callback, which performs device-specific operations upon ejection. When the PnP manager sends an IRP_MN_EJECT request for the device, KMDF calls the EvtDeviceEject routine with a handle to the device object.

 Note  KMDF events are not related to the kernel-dispatcher events that Windows provides as synchronization mechanisms. A driver cannot create, manipulate, or wait on a KMDF event; a KMDF event is simply a function. For time-related waits, KMDF provides timer objects.