KMDF Object Model Implementation


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:

Collection

String

DPC

Timer

Interrupt

WMI

Lookaside list

Work item

Registry key

 

Several objects for DMA: DMA enabler, DMA transaction, and common buffer

Several objects for hardware resources: resource range list, resource list, and resource requirements list

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.

Table 5-3: KMDF Object Types
Open table as spreadsheet

Object

Type

Description

Child list

WDFCHILDLIST

Represents a list of the child devices that the bus driver enumerates for a parent device.

Collection

WDFCOLLECTION

Describes a list of similar objects, such as resources or the devices for which a filter driver filters requests.

Device

WDFDEVICE

Represents an instance of a device. A driver typically has one WDFDEVICE object for each device that it controls.

DMA common buffer

WDFCOMMONBUFFER

Represents a buffer that can be accessed by both the device and the driver to perform DMA.

DMA enabler

WDFDMAENABLER

Enables DMA use by a device. A driver that handles device I/O operations has one WDFDMAENABLER object for each DMA channel within the device.

DMA transaction

WDFDMATRANSACTION

Represents a single DMA transaction.

DPC

WDFDPC

Represents a DPC.

Driver

WDFDRIVER

Represents the driver itself and maintains information about the driver, such as its entry points. Every driver has one WDFDRIVER object.

File

WDFFILEOBJECT

Represents a file object through which external drivers or applications can access the device.

Generic object

WDFOBJECT

Represents a generic object for the driver to use as required.

I/O queue

WDFQUEUE

Represents an I/O queue. A driver can have any number of WDFQUEUE objects.

I/O request

WDFREQUEST

Represents a request for device I/O.

I/O target

WDFIOTARGET

Represents a device stack to which the driver is forwarding an I/O request. A driver can have any number of WDFIOTARGET objects.

Interrupt

WDFINTERRUPT

Represents a device's interrupt object. Any driver that handles device interrupts has one WDFINTERRUPT object for each IRQ or message-signaled interrupt (MSI) that the device can trigger.

Lookaside list

WDFLOOKASIDE

Represents a dynamically sized list of identical buffers that are allocated from either paged or nonpaged pool.

Memory

WDFMEMORY

Represents memory that the driver uses, typically an input or output buffer that is associated with an I/O request.

Registry key

WDFKEY

Represents a registry key.

Resource list

WDFCMRESLIST

Represents the list of resources that have actually been assigned to the device.

Resource range list

WDFIORESLIST

Represents a possible configuration for a device.

Resource requirements list

WDFIORESREQLIST

Represents a set of I/O resource lists, which comprises all possible configurations for the device. Each element of the list is a WDFIORESLIST object.

String

WDFSTRING

Represents a counted Unicode string.

Synchronization: spin lock

WDFSPINLOCK

Represents a spin lock, which synchronizes access to data DISPATCH_LEVEL.

Synchronization: wait lock

WDFWAITLOCK

Represents a wait lock, which synchronizes access to data at PASSIVE_LEVEL.

Timer

WDFTIMER

Represents a timer that fires either once or periodically and causes a callback routine to run.

USB device

WDFUSBDEVICE

Represents a USB device.

USB interface

WDFUSBINTERFACE

Represents an interface on a USB device.

USB pipe

WDFUSBPIPE

Represents a configured pipe in a USB interface's setting.

WMI instance

WDFWMIINSTANCE

Represents an individual WMI data block that is associated with a particular provider.

WMI provider

WDFWMIPROVIDER

Represents the schema for WMI data blocks that the driver provides.

Work item

WDFWORKITEM

Represents a work item, which runs in a system thread at PASSIVE_LEVEL.

 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.




Developing Drivers with the Microsoft Windows Driver Foundation
Developing Drivers with the Windows Driver Foundation (Pro Developer)
ISBN: 0735623740
EAN: 2147483647
Year: 2007
Pages: 224

Similar book on Amazon
Windows Internals, Part 1: Covering Windows Server 2008 R2 and Windows 7
Windows Internals, Part 1: Covering Windows Server 2008 R2 and Windows 7
Windowsu00ae Internals: Including Windows Server 2008 and Windows Vista, Fifth Edition (Pro Developer)
Windowsu00ae Internals: Including Windows Server 2008 and Windows Vista, Fifth Edition (Pro Developer)
Advanced Windows Debugging
Advanced Windows Debugging
The Windows 2000 Device Driver Book: A Guide for Programmers (2nd Edition)
The Windows 2000 Device Driver Book: A Guide for Programmers (2nd Edition)

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net