Understanding the Windows I/O System

Kernel-Mode Driver Framework (KMDF)

We’ve already discussed some details about the Windows Driver Foundation (WDF) in Chapter 2, “System Architecture,” in Part 1. In this section, we’ll take a deeper look at the components and functionality provided by the kernel-mode part of the framework, KMDF. Note that this section will only briefly touch on some of the core architecture of KMDF. For a much more complete overview on the subject, please refer to http://msdn.microsoft.com/en-us/library/windows/hardware/gg463370.aspx.

Structure and Operation of a KMDF Driver

First, let’s take a look at which kinds of drivers or devices are supported by KMDF. In general, any WDM-conformant driver should be supported by KMDF, as long as it performs standard I/O processing and IRP manipulation. KMDF is not suitable for drivers that don’t use the Windows kernel API directly but instead perform library calls into existing port and class drivers. These types of drivers cannot use KMDF because they only provide callbacks for the actual WDM drivers that do the I/O processing. Additionally, if a driver provides its own dispatch functions instead of relying on a port or class driver, IEEE 1394 and ISA, PCI, PCMCIA, and SD Client (for Secure Digital storage devices) drivers can also make use of KMDF.

Although KMDF provides an abstraction on top of WDM, the basic driver structure shown earlier also generally applies to KMDF drivers. At their core, KMDF drivers must have the following functions:

• An initialization routine Just like any other driver, a KMDF driver has a DriverEntry function that initializes the driver. KMDF drivers will initiate the framework at this point and perform any configuration and initialization steps that are part of the driver or part of describing the driver to the framework. For non–Plug and Play drivers, this is where the first device object should be created.

• An add-device routine KMDF driver operation is based on events and callbacks (described shortly), and the EvtDriverDeviceAdd callback is the single most important one for PnP devices because it receives notifications when the PnP manager in the kernel enumerates one of the driver’s devices.

• One or more EvtIo* routines Just like a WDM driver’s dispatch routines, these callback routines handle specific types of I/O requests from a particular device queue. A driver typically creates one or more queues in which KMDF places I/O requests for the driver’s devices. These queues can be configured by request type and dispatching type.

The simplest KMDF driver might need to have only an initialization and add-device routine because the framework will provide the default, generic functionality that’s required for most types of I/O processing, including power and Plug and Play events. In the KMDF model, events refer to run-time states to which a driver can respond or during which a driver can participate. These events are not related to the synchronization primitives (synchronization is discussed in Chapter 3 in Part 1), but are internal to the framework.

For events that are critical to a driver’s operation, or which need specialized processing, the driver registers a given callback routine to handle this event. In other cases, a driver can allow KMDF to perform a default, generic action instead. For example, during an eject event (EvtDeviceEject), a driver can choose to support ejection and supply a callback or to fall back to the default KMDF code that will tell the user that the device is not ejectable. Not all events have a default behavior, however, and callbacks must be provided by the driver. One notable example is the EvtDriverDeviceAdd event that is at the core of any Plug and Play driver.

lkd> !wdfkd.wdfldr
 LoadedModuleList      0xfffff880010682d8
----------------------------------
LIBRARY_MODULE  fffffa8002776120
  Version       v1.9 build(7600)
  Service       \Registry\Machine\System\CurrentControlSet\Services\
Wdf01000
  ImageName     Wdf01000.sys
  ImageAddress  0xfffff88000c00000
  ImageSize     0xa4000
  Associated Clients: 16

ImageName        Version    WdfGlobals          FxGlobals
               ImageAddress          ImageSize
peauth.sys       v1.7(6001) 0xfffffa8004754210  0xfffffa80047540c0  
               0xfffff880074cc000    0x000a6000
scfilter.sys     v1.5(6000) 0xfffffa8002ef34e0  0xfffffa8002ef3390  
               0xfffff880040b3000    0x0000e000
WinUSB.sys       v1.9(7600) 0xfffffa8002eefd20  0xfffffa8002eefbd0
               0xfffff88004000000    0x00011000
monitor.sys      v1.9(7600) 0xfffffa8004854a10  0xfffffa80048548c0
               0xfffff8800412a000    0x0000e000
vmswitch.sys     v1.5(6000) 0xfffffa8002de5d60  0xfffffa8002de5c10
               0xfffff88003e9b000    0x00068000
vmbus.sys        v1.5(6000) 0xfffffa8002d7fcf0  0xfffffa8002d7fba0
               0xfffff88003e5f000    0x0003c000
Vid.sys          v1.5(6000) 0xfffffa8002ddacf0  0xfffffa8002ddaba0
               0xfffff88002a00000    0x00033000
umbus.sys        v1.9(7600) 0xfffffa8002e57e70  0xfffffa8002e57d20
               0xfffff880035db000    0x00012000
storvsp.sys      v1.5(6000) 0xfffffa8002e48b10  0xfffffa8002e489c0
               0xfffff88003575000    0x00023000
CompositeBus.sys v1.9(7600) 0xfffffa8002d79160  0xfffffa8002d79010
               0xfffff88002936000    0x00010000
HDAudBus.sys     v1.7(6001) 0xfffffa8002e357f0  0xfffffa8002e356a0
               0xfffff880037a9000    0x00024000
intelppm.sys     v1.9(7600) 0xfffffa8002c518f0  0xfffffa8002c517a0
               0xfffff880027e7000    0x00016000
cdrom.sys        v1.9(7600) 0xfffffa80028bf8f0  0xfffffa80028bf7a0
               0xfffff880011c4000    0x0002a000
vmstorfl.sys     v1.5(6000) 0xfffffa8002b2cdd0  0xfffffa8002b2cc80
               0xfffff8800144a000    0x00010000
vdrvroot.sys     v1.9(7600) 0xfffffa80027887c0  0xfffffa8002788670
               0xfffff8800139c000    0x0000d000
msisadrv.sys     v1.9(7600) 0xfffffa80029c5430  0xfffffa80029c52e0
               0xfffff8800135f000    0x0000a000
----------------------------------
Total:  1  library  loaded

KMDF Data Model

The KMDF data model is object-based, much like the model for the kernel, but it does not make use of the object manager. Instead, KMDF manages its own objects internally, exposing them as handles to drivers and keeping the actual data structures opaque. For each object type, the framework provides routines to perform operations on the object, such as WdfDeviceCreate, which creates a device. Additionally, objects can have specific data fields or members that can be accessed by Get/Set (used for modifications that should never fail) or Assign/Retrieve APIs (used for modifications that can fail). For example, the WdfInterruptGetInfo function returns information on a given interrupt object (WDFINTERRUPT).

Also unlike the implementation of kernel objects, which all refer to distinct and isolated object types, KMDF objects are all part of a hierarchy—most object types are bound to a parent. The root object is the WDFDRIVER structure, which describes the actual driver. The structure and meaning is analogous to the DRIVER_OBJECT structure provided by the I/O manager, and all other KMDF structures are children of it. The next most important object is WDFDEVICE, which refers to a given instance of a detected device on the system, which must have been created with WdfDeviceCreate. Again, this is analogous to the DEVICE_OBJECT structure that’s used in the WDM model and by the I/O manager. Table 8-5 lists the object types supported by KMDF.

Table 8-5 KMDF Object Types

For each of these objects, other KMDF objects can be attached as children—some objects have only one or two valid parents, while other objects can be attached to any parent. For example, a WDFINTERRUPT object must be associated with a given WDFDEVICE, but a WDFSPINLOCK or WDFSTRING can have any object as a parent, allowing fine-grained control over their validity and usage and reducing global state variables. Figure 8-30 shows the entire KMDF object hierarchy.

Note that the associations mentioned earlier and shown in the figure are not necessarily immediate. The parent must simply be on the hierarchy chain, meaning one of the ancestor nodes must be of this type. This relationship is useful to implement because object hierarchies affect not only the objects’ locality but also their lifetime. Each time a child object is created, a reference count is added to it by its link to its parent. Therefore, when a parent object is destroyed, all the child objects are also destroyed, which is why associating objects such as WDFSTRING or WDFMEMORY with a given object, instead of the default WDFDRIVER object, can automatically free up memory and state information when the parent object is destroyed.

Closely related to the concept hierarchy is KMDF’s notion of object context. Because KMDF objects are opaque, as discussed, and are associated with a parent object for locality, it becomes important to allow drivers to attach their own data to an object in order to track certain specific information outside the framework’s capabilities or support.

Figure 8-30 KMDF object hierarchy

Object contexts allow all KMDF objects to contain such information, and they additionally allow multiple object context areas, which permit multiple layers of code inside the same driver to interact with the same object in different ways. In the WDM model, the device extension data structure allows such information to be associated with a given device, but with KMDF even a spinlock or string can contain context areas. This extensibility allows each library or layer of code responsible for processing an I/O to interact independently of other code, based on the context area that it works with, and allows a mechanism similar to inheritance.

Finally, KMDF objects are also associated with a set of attributes that are shown in Table 8-6. These attributes are usually configured to their defaults, but the values can be overridden by the driver when creating the object by specifying a WDF_OBJECT_ATTRIBUTES structure (similar to the object manager’s OBJECT_ATTRIBUTES structure that’s used when creating a kernel object).

Table 8-6 KMDF Object Attributes

KMDF I/O Model

The KMDF I/O model follows the WDM mechanisms discussed earlier in the chapter. In fact, one can even think of the framework itself as a WDM driver, since it uses kernel APIs and WDM behavior to abstract KMDF and make it functional. Under KMDF, the framework driver sets its own WDM-style IRP dispatch routines and takes control over all IRPs sent to the driver. After being handled by one of three KMDF I/O handlers (which we’ll describe shortly), it then packages these requests in the appropriate KMDF objects, inserts them in the appropriate queues if required, and performs driver callback if the driver is interested in those events. Figure 8-31 describes the flow of I/O in the framework.

Based on the IRP processing discussed for WDM drivers earlier, KMDF performs one of the following three actions:

• Sends the IRP to the I/O handler, which processes standard device operations

• Sends the IRP to the PnP and power handler that processes these kinds of events and notifies other drivers if the state has changed

• Sends the IRP to the WMI handler, which handles tracing and logging.

These components will then notify the driver of any events it registered for, potentially forward the request to another handler for further processing, and then complete the request based on an internal handler action or as the result of a driver call. If KMDF has finished processing the IRP but the request itself has still not been fully processed, KMDF will take one of the following actions:

• For bus drivers and function drivers, complete the IRP with STATUS_INVALID_DEVICE_REQUEST

• For filter drivers, forward the request to the next lower driver

  

  Figure 8-31 KMDF I/O flow and IRP processing

I/O processing by KMDF is based on the mechanism of queues (WDFQUEUE, not the KQUEUE object discussed in the earlier section on I/O completion and in Chapter 3 in Part 1). KMDF queues are highly scalable containers of I/O requests (packaged as WDFREQUEST objects) and provide a rich feature set beyond merely sorting the pending I/Os for a given device. For example, queues also track currently active requests and support I/O cancellation, I/O concurrency (the ability to perform and complete more than one I/O request at a time), and I/O synchronization (as noted in the list of object attributes in Table 8-6). A typical KMDF driver creates at least one queue (if not more) and associates one or more events with each queue, as well as some of the following options:

• The callbacks registered with the events associated with this queue.

• The power management state for the queue. KMDF supports both power-managed and nonpower-managed queues. For the former, the I/O handler will handle waking up the device when required (and when possible), arm the idle timer when the device has no I/Os queued up, and call the driver’s I/O cancellation routines when the system is switching away from a working state.

• The dispatch method for the queue. KMDF can deliver I/Os from a queue either in a sequential, parallel, or manual mode. Sequential I/Os are delivered one at a time (KMDF waits for the driver to complete the previous request), while parallel I/Os are delivered to the driver as soon as possible. In manual mode, the driver must manually retrieve I/Os from the queue.

• Whether or not the queue can accept zero-length buffers, such as incoming requests that don’t actually contain any data.

Based on the mechanism of queues, the KMDF I/O handler can perform several possible tasks upon receiving either a create, close, cleanup, write, read, or device control (IOCTL) request:

• For create requests, the driver can request to be immediately notified through EvtDeviceFileCreate, or it can create a nonmanual queue to receive create requests. It must then register an EvtIoDefault callback to receive the notifications. Finally, if none of these methods are used, KMDF will simply complete the request with a success code, meaning that by default, applications will be able to open handles to KMDF drivers that don’t supply their own code.

• For cleanup and close requests, the driver will be immediately notified through EvtFileCleanup and EvtFileClose callbacks, if registered. Otherwise, the framework will simply complete with a success code.

• Finally, Figure 8-32 illustrates the flow of an I/O request to a KMDF driver for the most common driver operations (read, write, and I/O control codes).

Figure 8-32 Handling read, write, and IOCTL I/O requests by KMDF