Windows® Internals, Sixth Edition, Part 2

DMA Enabler

WDFDMAENABLER

Enables DMA on a given channel for a driver.

DMA Transaction

WDFDMATRANSACTION

Instance of a DMA transaction.

Driver

WDFDRIVER

Root object for the driver; represents the driver, its parameters, and its callbacks, among other items.

File

WDFFILEOBJECT

Instance of a file object that can be used as a channel for communication between an application and the driver.

Generic Object

WDFOBJECT

Allows driver-defined custom data to be wrapped inside the framework’s object data model as an object.

Interrupt

WDFINTERRUPT

Instance of an interrupt that the driver must handle.

I/O Queue

WDFQUEUE

Represents a given I/O queue.

I/O Request

WDFREQUEST

Represents a given request on a WDFQUEUE.

I/O Target

WDFIOTARGET

Represents the device stack being targeted by a given WDFREQUEST.

Look-Aside List

WDFLOOKASIDE

Describes an executive look-aside list.

Memory

WDFMEMORY

Describes a region of paged or nonpaged pool.

Registry Key

WDFKEY

Describes a registry key.

Resource List

WDFCMRESLIST

Identifies the hardware resources assigned to a WDFDEVICE.

Resource Range List

WDFIORESLIST

Identifies a given possible hardware resource range for a WDFDEVICE.

Resource Requirements List

WDFIORESREQLIST

Contains an array of WDFIORESLIST objects describing all possible resource ranges for a WDFDEVICE.

Spinlock

WDFSPINLOCK

Describes a spinlock (see Chapter 3 in Part 1 for more information).

String

WDFSTRING

Describes a Unicode string structure.

Timer

WDFTIMER

Describes an executive timer (see Chapter 3 in Part 1 for more information).

USB Device

WDFUSBDEVICE

Identifies the one instance of a USB device.

USB Interface

WDFUSBINTERFACE

Identifies one interface on the given WDFUSBDEVICE.

USB Pipe

WDFUSBPIPE

Identifies a pipe to an endpoint on a given WDFUSBINTERFACE.

Wait Lock

WDFWAITLOCK

Represents a kernel dispatcher event object.

WMI Instance

WDFWMIINSTANCE

Represents a WMI data block for a given WDFWMIPROVIDER.

WMI Provider

WDFWMIPROVIDER

Describes the WMI schema for all the WDFWMIINSTANCE objects supported by the driver.

Work Item

WDFWORKITEM

Describes an executive work item.

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

Attribute

Description

ContextSizeOverride

Size of the object context area.

ContextTypeInfo

Type of the object context area.

EvtCleanupCallback