UMDF Object Model Implementation


In UMDF, the framework maintains a set of framework objects, and the driver creates a callback object that corresponds to each framework object for which the driver requires an event callback. The callback objects expose callback interfaces that are defined by the framework.

UMDF drivers use the following types of objects:

Driver-created file

I/O completion parameters

Base object

I/O target

Driver

Memory

Device

USB device

File

USB I/O target

I/O request

USB interface

I/O queue

 

UMDF objects and interfaces are based on the COM programming pattern. UMDF uses only the query-interface and reference-counting features of COM; it does not depend on the entire COM infrastructure and runtime library.

Chapter 18, "An Introduction to COM," provides information about COM.

UMDF Naming Conventions

UMDF follows naming conventions for the interfaces that it implements and the callback interfaces that it defines.

 UMDF interface names  The UMDF-implemented interfaces are named:

  • IWDFObject[Description]

where:

  • Object specifies the UMDF object that exposes the interface.

  • Description is additional information that indicates which aspect of the object it acts on.

For example, framework device objects expose the IWDFDevice interface, which supports methods that manipulate a framework device object. Framework I/O target objects expose the IWDFIoTarget and IWDFIoTargetStateManagement interfaces.

 UMDF method names  Methods in UMDF interfaces are named:

  • ActionQualifier

where:

  • Action is a verb that indicates the action that the function performs.

  • Qualifier specifies the object or data that is the target of the action.

For example, the IWDFDevice interface includes the CreateIoQueue and ConfigureRequestDispatching methods.

 UMDF property names  UMDF properties are named:

  • {Set|Get}Data

  • {Assign|Retrieve}Data

where:

  • 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 properties without failure. Functions with Assign and Retrieve in their names can fail and return an HRESULT that contains a status value.

For example, IWDFDevice::GetPnpState and IWDFDevice::SetPnpState set and return the value of individual Plug and Play characteristics for a device object.

 UMDF event callback interface names  Event callback interfaces for UMDF objects are generally named:

  • IObjectCallbackDescription

where:

  • Object identifies the object type.

  • Description indicates what the interface does.

For example, the IQueueCallbackWrite interface is implemented on a queue callback object. It supports a method that the framework calls in response to a write request.

The IPnpCallbackXxx interfaces are an exception. Although these interfaces have Pnp in their names, they are implemented on device objects. They support methods that respond to Plug and Play events.

UMDF methods within the callback interfaces are named:

  • OnEvent

where:

  • Event indicates the event for which the framework invokes the callback method.

For example, the framework calls the IQueueCallbackWrite::OnWrite method when a write request arrives for the device object. The IPnpCallback::OnD0Entry method is called when the device enters the working power state.

UMDF Framework Objects and Interfaces

Table 5-1 lists the interfaces that the framework implements on each type of object.

Table 5-1: UMDF Framework Objects and Interfaces
Open table as spreadsheet

Type of object

Object description

Interfaces

Interface description

Base object

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

IWDFObject

Supports actions common to all objects, such as locking, deletion, and managing the context area.

Device

Represents a device object. A driver typically has one device object for each device that it controls. Inherits from IWDFObject.

IWDFDevice

Provides device-specific information and creates device-specific objects.

  

IWDFFileHandleTargetFactory

Creates an I/O target object based on a file handle.

  

IWDFUsbTargetFactory

Creates a USB I/O target device object.

Driver

Represents the driver object itself. Every driver has one driver object. Inherits from IWDFObject.

IWDFDriver

Creates driver child objects and provides version information.

File

Represents a framework file object that was opened by the CreateFile function, through which applications can access the device. Inherits from IWDFObject.

IWDFFile

Returns information about the file and device that are associated with a file handle.

Driver-created file

Represents a framework file object that the driver created. Inherits from IWDFFile.

IWDFDriverCreatedFile

Closes a driver-created file.

I/O queue

Represents an I/O queue, which controls the flow of I/O in the driver. A driver can have any number of I/O queues. Inherits from IWDFObject.

IWDFIoQueue

Configures, manages, and retrieves requests and information from a queue.

I/O request

Represents a request for device I/O. Inherits from IWDFObject.

IWDFIoRequest

Formats, sends, cancels, and returns information about an I/O request.

I/O request completion information

Represents the completion information for an I/O request.

IWDFRequestCompletionParams

Returns status, number of bytes, and request type for a completed I/O request.

I/O request completion parameters

Exposes the parameters returned in a completed I/O request. Inherits from IWDF-RequestCompletionParams.

IWDFIoRequestCompletionParams

Returns buffers for read, write, and device I/O control requests.

I/O target

Represents the next-lower driver in the device stack, to which the driver sends I/O requests. Inherits from IWDFObject.

IWDFIoTarget

Formats and cancels I/O requests and returns information about the target file.

  

IWDFIoTargetStateManagement

Monitors and controls the state of an I/O target.

Memory

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

IWDFMemory

Copies data to and from a memory buffer and returns information about the buffer.

Property store

Represents an object through which a driver can maintain persistent data in the registry between driver loads and unloads.

IWDFNamedPropertyStore

Enables a driver to query and set information in the registry.

USB interface

Represents an interface on a USB device. Inherits from IWDFObject.

IWDFUsbInterface

Returns information about and selects a setting for a USB interface.

USB target device

Represents a USB device object that is an I/O target. Inherits from IWDFIoTarget.

IWDFUsbTargetDevice

Formats requests for and returns information about a USB target device.

USB target pipe

Represents a USB pipe that is an I/O target. Inherits from IWDFIoTarget.

IWDFUsbTargetPipe

Manages and returns information about a USB pipe.

USB I/O request completion parameters

Exposes the parameters returned in a completed I/O request to a USB target. Inherits from IWDFRequestCompletionParams.

IWDFUsbRequestCompletionParams

Returns request type and buffers for USB read, write, and device I/O control requests.

UMDF Driver Callback Objects and Interfaces

A UMDF driver assigns a callback object to each framework object whose events the driver is interested in and implements callback interfaces for those events on the callback object. Every UMDF driver must implement one driver callback object for the driver itself and one device callback object for each device that it supports. Most drivers also implement a queue callback object for each queue.

The driver must implement the IUnknown interface for each callback object. The driver can do this in any of several ways. The UMDF Echo, Skeleton, and USB samples include the Comsup.h header file, which implements IUnknown in the CUnknown base class. In your own driver, you can include Comsup.h and list CUnknown as a base class when you declare the driver's classes.

Chapter 13, "UMDF Driver Template," provides details about how to use the Skeleton sample as a template for your own driver development.

Table 5-2 lists the possible callback interfaces that a driver can implement.

Table 5-2: UMDF Driver Callback Objects and Interfaces
Open table as spreadsheet

Type of object

Callback interfaces

Description of interface

All objects

IObjectCleanup

Provides processing that is required before an object is disposed, typically releasing any circular references.

Driver

IDriverEntry

Provides the main entry point from the framework into the driver and methods to initialize the driver and add its devices. This object is required for all drivers.

Unlike other callback interfaces, the driver does not register IDriverEntry with any particular object. Instead, the framework requests this interface from the driver's CoClass object when it loads the driver.

Device

IPnpCallback

Handles device stop, removal, and power state changes.

 

IPnpCallbackHardware

Provides hardware-related operations before device power-up and after device power-down.

 

IPnpCallbackSelfManagedIo

Enables the driver to perform actions when the framework starts and stops I/O processing at specific Plug and Play and power management state transitions.

File

IFileCallbackCleanup

Handles cleanup requests for file objects on a specific device, typically so that the driver can cancel any outstanding I/O requests for the file before it is closed.

 

IFileCallbackClose

Receives close notifications for file objects on a specific device so that the driver can release file-specific resources.

I/O queue

IQueueCallbackCreate

Handles file create requests.

 

IQueueCallbackDefaultIoHandler

Handles create, device I/O control, read, and write requests for which no other interface has been implemented.

 

IQueueCallbackDeviceIoControl

Handles device I/O control requests.

 

IQueueCallbackIoResume

Resumes processing an I/O request after its queue has been stopped.

 

IQueueCallbackIoStop

Stops processing an I/O request because its queue is stopping.

 

IQueueCallbackStateChange

Notifies the driver when the state of a queue changes.

 

IQueueCallbackRead

Handles read requests.

 

IQueueCallbackWrite

Handles write requests.

I/O request

IImpersonateCallback

Performs tasks while the driver impersonates the client that issued the I/O request.

 

IRequestCallbackCancel

Performs tasks after an I/O request is canceled.

 

IRequestCallbackRequestCompletion

Performs tasks when an I/O request is completed.

When an event occurs, the framework calls methods on the appropriate callback interfaces so that the driver can respond to the events that are associated with the request. For example, if the driver has configured a queue for read requests, the framework calls methods in the queue callback object's IQueueCallbackRead interface when it receives such a request.

Tip 

Framework objects and callback objects are not required to correspond on a one-to-one basis. The driver can do whatever makes the most sense for the callback and the driver.

For example, consider I/O cancellation and completion callbacks. You can implement these interfaces on whichever callback object seems most appropriate. If your driver has a queue that also manages continuous reads on an interrupt pipe, then it might make sense to implement the cancellation and completion callback interfaces on the queue. Likewise, if your driver allocates a context area for each request to track the state of the request, then you could create a callback object instead and implement the I/O cancellation and completion callback interfaces on the callback object.

UMDF Example: Objects and Callback Interfaces

Figure 5-1 shows the primary callback interfaces that the Fx2_Driver sample implements for the driver and device objects. IUnknown-which all COM objects must support-is not shown, nor are the objects and callback interfaces that support the driver's I/O queues.

image from book
Figure 5-1: Driver and device callback objects in the Fx2_Driver sample

As the figure shows, the framework implements a driver object and a device object, and the Fx2_Driver sample creates a driver callback object and a device callback object. The framework driver object uses the driver callback object's IDriverEntry interface, and the driver callback object, in turn, uses the IWDFDriver interface on the framework driver object.

The framework device object exposes the IWDFDevice and IWDFDeviceInitialize interfaces, which the device callback object uses. The device callback object also implements the IPnpCallbackHardware and IPnpCallback interfaces, which the framework device object uses.




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