List of Listings

Chapter 5: WDF Object Model

Listing 5-1: Creating callback and framework objects in a UMDF driver

Listing 5-2: Creating an object in a KMDF driver

Listing 5-3: Deleting an object in a UMDF driver

Listing 5-4: Deleting a KMDF object

Listing 5-5: Storing context data in a callback object

Listing 5-6: Creating a context area in a UMDF object

Listing 5-7: Sample OnCleanup method for a UMDF context area

Listing 5-8: Declaring the context type for a KMDF object

Listing 5-9: Initializing an attribute structure with context area information

Listing 5-10: Assigning a context area to an existing KMDF object

Chapter 6: Driver Structure and Initialization

Listing 6-1: UMDF driver callback object creation

Listing 6-2: KMDF sample DriverEntry function

Listing 6-3: UMDF framework device object creation

Listing 6-4: UMDF: creating a device interface

Listing 6-5: Definition of a device object context area

Listing 6-6: Sample EvtDriverDeviceAdd callback function

Listing 6-7: Assigning an SDDL string to a raw PDO

Chapter 7: Plug and Play and Power Management

Listing 7-1: Sample PnP initialization in a UMDF filter driver

Listing 7-2: Sample PnP initialization in a KMDF software-only filter driver

Listing 7-3: Sample IPnpCallbackHardware::OnPrepareHardware method

Listing 7-4: Sample IPnpCallbackHardware::OnReleaseHardware method

Listing 7-5: Sample IPnpCallback::OnD0Entry method

Listing 7-6: Sample IPnpCallback::OnD0Exit method

Listing 7-7: Sample IPnpCallback::OnSurpriseRemoval method

Listing 7-8: EvtDriverDeviceAdd for simple hardware function driver

Listing 7-9: EvtDeviceD0Entry callback for simple hardware function driver

Listing 7-10: EvtDeviceD0Exit callback for simple hardware function driver

Listing 7-11: Sample USB driver's EvtDevicePrepareHardware callback

Listing 7-12: Initializing wake and idle support in a KMDF USB driver

Chapter 8: I/O Flow and Dispatching

Listing 8-1: Retrieving a memory object and buffer pointer in a UMDF driver

Listing 8-2: EvtIoInCallerContext callback function

Listing 8-3: Creating and initializing a default UMDF queue

Listing 8-4: Creating a manual queue in a UMDF driver

Listing 8-5: Creating a default queue in a KMDF driver

Listing 8-6: Creating a nondefault queue in a KMDF driver

Listing 8-7: Finding a request in a manual KMDF queue

Listing 8-8: UMDF driver's OnCreateFile method

Listing 8-9: Using impersonation

Listing 8-10: OnImpersonation callback

Listing 8-11: Registering the EvtDeviceFileCreate callback

Listing 8-12: IQueueCallbackWrite::OnWrite method in a UMDF driver

Listing 8-13: EvtIoRead callback function in a KMDF driver

Listing 8-14: IQueueCallbackDeviceIoControl::OnDeviceIoControl method in a UMDF driver

Listing 8-15: EvtIoDeviceControl callback in a KMDF driver

Listing 8-16: IQueueCallbackDefaultIoHandler::OnDefaultIoHandler in a UMDF driver

Listing 8-17: EvtIoDefault callback in KMDF driver

Listing 8-18: Registering self-managed I/O callbacks in a KMDF driver

Listing 8-19: Initializing self-managed I/O in a KMDF driver

Listing 8-20: Starting a watchdog timer in a KMDF driver

Listing 8-21: Suspending self-managed I/O in a KMDF driver

Listing 8-22: Restarting self-managed I/O in a KMDF driver

Listing 8-23: Self-managed I/O cleanup in a KMDF driver

Chapter 9: I/O Targets

Listing 9-1: Creating and opening a remote I/O target in a KMDF driver

Listing 9-2: EvtIoTargetQueryRemove callback in a KMDF driver

Listing 9-3: Creating a WDF I/O request in a UMDF driver

Listing 9-4: Creating a WDF I/O request object in a KMDF driver

Listing 9-5: Calling CreatePreallocatedWdfMemory in a UMDF driver

Listing 9-6: Creating a memory object in a KMDF driver

Listing 9-7: Formatting a write request in a UMDF driver

Listing 9-8: Formatting a read request in a KMDF driver

Listing 9-9: Sending a request to the default I/O target in a UMDF driver

Listing 9-10: Completing a sent request in a UMDF driver

Listing 9-11: Using the send-and-forget option in a KMDF driver

Listing 9-12: Formatting and sending a read request in a KMDF driver

Listing 9-13: Reusing an I/O request object in a KMDF driver

Listing 9-14: Canceling all requests for a file in a UMDF driver

Listing 9-15: Canceling a request in a KMDF driver

Listing 9-16: Creating a file handle I/O target in a UMDF driver

Listing 9-17: Creating a USB target device object in a UMDF driver

Listing 9-18: Retrieving a USB interface in a UMDF driver

Listing 9-19: Configuring the USB pipes in a UMDF driver

Listing 9-20: Configuring USB pipes in a UMDF driver

Listing 9-21: Creating a USB target device object in a KMDF driver

Listing 9-22: Selecting a USB device configuration in a KMDF driver

Listing 9-23: Enumerating pipes for a USB interface in a KMDF driver

Listing 9-24: Retrieving USB device information in a KMDF driver

Listing 9-25: Sending a device I/O control request to a USB device in a UMDF driver

Listing 9-26: Retrieving results from a USB I/O request in a UMDF driver

Listing 9-27: Sending an asynchronous read request to a USB target pipe in a KMDF driver

Listing 9-28: Retrieving USB request completion parameters in a KMDF driver

Chapter 10: Synchronization

Listing 10-1: Setting synchronization scope in a KMDF driver

Listing 10-2: Setting automatic serialization for a DPC object

Listing 10-3: Creating a wait lock in a KMDF driver

Listing 10-4: Using a wait lock in a KMDF driver

Listing 10-5: Creating a spin lock in a KMDF driver

Listing 10-6: Acquiring and releasing a spin lock

Listing 10-7: Canceling a request using framework synchronization

Listing 10-8: Using a collection to synchronize request cancellation in a KMDF driver

Chapter 11: Driver Tracing and Diagnosability

Custom Trace Message Function Definitions for Fx2_Driver

Listing 11-1: WPP macros for Fx2_Driver

RUN_WPP for Osrusbfx2

Including a TMH File for ReadWriteQueue.cpp from Fx2_Driver

Including a TMH File for Interrupt.c from Osrusbfx2

Listing 11-2: Macro definition format for WPP_CONTROL_GUIDS

WPP_DEFINE_CONTROL_GUID for Fx2_Driver

WPP_DEFINE_CONTROL_GUID for Osrusbfx2

Definition of MYDRIVER_TRACING_ID

Initializing WPP Tracing in DllMain

Initializing WPP Tracing in DriverEntry

Cleaning Up WPP Tracing in DllMain

Cleaning Up WPP Tracing in EvtCleanupCallback

Cleaning up WPP Tracing in DriverEntry

Adding a Trace Message to Fx2_Driver

Adding a Trace Message to Osrusbfx2

Listing 11-3: Tracelog commands to set environment variables

Listing 11-4: A real-time trace session using Tracelog and Tracefmt

Chapter 12: WDF Support Objects

Listing 12-1: Creating a lookaside list

Listing 12-2: Allocating memory from a lookaside list

Listing 12-3: Creating a named property store

Listing 12-4: Retrieving information from a property store

Listing 12-5: Setting information in a property store

Listing 12-6: Reading a registry key during device object initialization

Listing 12-7: Creating a general object in a UMDF driver

Listing 12-8: Creating a general object in a KMDF driver

Listing 12-9: Creating a collection object in a KMDF driver

Listing 12-10: Adding an object to a collection

Listing 12-11: Removing an object from a collection

Listing 12-12: Creating and starting a timer object

Listing 12-13: Stopping and deleting a timer object

Listing 12-14: Initializing WMI support

Listing 12-15: Sample EvtWmiInstanceQueryInstance callback

Listing 12-16: Sample EvtWmiInstanceSetInstance callback

Listing 12-17: Sample EvtWmiInstanceSetItem callback

Chapter 13: UMDF Driver Template

Listing 13-1: The Skeleton sample DllMain implementation

Listing 13-2: WPP-related code from the Skeleton sample Internal.h file

Listing 13-3: The Skeleton sample DllGetClassObject implementation

Listing 13-4: The Skeleton sample IClassFactory::CreateInstance implementation

Listing 13-5: The Skeleton sample CMyDriver::CreateInstance implementation

Listing 13-6: The Skeleton sample IDriverEntry::OnDeviceAdd implementation

Listing 13-7: The Skeleton sample CMyDevice::Initialize implementation

Listing 13-8: The Skeleton sample Sources file

Listing 13-9: The Skeleton sample Exports.def file

Listing 13-10: The Skeleton sample version resource file

Listing 13-11: The Skeleton sample INX file

Chapter 14: Beyond the Frameworks

Listing 14-1: How to call the Windows API from a UMDF driver

Listing 14-2: How to call an I/O manager function from a KMDF driver

Listing 14-3: How to register the EvtDeviceWdmPreprocessIrp callback

Listing 14-4: How to handle a WDM IRP in an EvtDeviceWdmPreprocessIrp callback

Chapter 15: Scheduling, Thread Context, and IRQL

Listing 15-1: Creating and queuing a work item

Listing 15-2: Work item callback function

Chapter 16: Hardware Resources and Interrupts

Listing 16-1: Mapping hardware resources

Listing 16-2: Unmapping hardware resources

Listing 16-3: Creating an interrupt object

Listing 16-4: Enabling interrupts

Listing 16-5: Disabling interrupts

Listing 16-6: Servicing an interrupt in an EvtInterruptIsr callback

Listing 16-7: Deferred interrupt processing in an EvtInterruptDpc callback

Listing 16-8: Using the interrupt spin lock

Chapter 17: Direct Memory Access

Listing 17-1: DMA initialization

Listing 17-2: DMA initiation

Listing 17-3: Sample EvtProgramDma callback

Listing 17-4: DMA completion processing

Listing 17-5: Output of KMDF debugger extensions for DMA

Chapter 18: An Introduction to COM

Listing 18-1: Declaration for IWDFObject from Wudfddi.idl

Listing 18-2: How to invoke a method on an interface

Listing 18-3: How to receive an interface pointer through a callback method

Listing 18-4: Declaration of the IWDFDevice::CreateRequest method

Listing 18-5: How to use an object creation method-from Fx2_Driver

Listing 18-6: How to request a new interface on an existing object

Listing 18-7: A typical DllMain implementation

Listing 18-8: A typical DllGetClassObject implementation

Listing 18-9: The driver callback object's class factory declaration for the Fx2_Driver sample

Listing 18-10: The Fx2_Driver sample's IClassFactory::CreateInstance implementation

Listing 18-11: Fx2_Driver sample's IClassFactory::LockServer implementation

Listing 18-12: A typical class declaration for a simple COM object

Listing 18-13: A class declaration for the Fx2_Driver sample's base implementation of IUnknown

Listing 18-14: A class declaration for the Fx2_Driver sample's driver callback object

Listing 18-15: Fx2_Driver sample's base implementation of AddRef

Listing 18-16: Fx2_Driver sample's base implementation of Release

Listing 18-17: An interface-specific implementation of AddRef

Listing 18-18: Fx2_Driver sample's base implementation of IUnknown

Listing 18-19: Fx2_Driver sample's base implementation of QueryInterface

Listing 18-20: Declaration of the Fx2_Driver sample's driver callback object

Chapter 19: How to Build WDF Drivers

Listing 19-1: A minimal KMDF Sources file

Listing 19-2: The Fx2_Driver Sources file

Listing 19-3: The Fx2_Driver Makefile.inc file

Listing 19-4: The Osrusbfx2 Sources file

Listing 19-5: The Osrusbfx2 Makefile.inc file

Listing 19-6: The KMDF Featured Toaster Makefile.inc file

Chapter 20: How to Install WDF Drivers

Listing 20-1: Fx2_Driver sample [Version] section

Listing 20-2: [Manufacturer] sections from the Osrusbfx2 sample's INX and INFs

Listing 20-3: [Microsoft] section from the Osrusbfx2 sample's INF

Listing 20-4: Fx2_Driver INF co-installer sections

Listing 20-5: Osrusbfx2 INF co-installer sections

Listing 20-6: Featured Toaster INF CatalogFile entry

Chapter 21: Tools for Testing WDF Drivers

Listing 21-1: Example of crash in win32k!GreEnableEUDC

Listing 21-2: Example display of pool allocation counters

Listing 21-3: Example !wdfkd.wdfdriverinfo output for WdfRawBusEnumTest driver

Listing 21-4: Example debugger output from UMDF Verifier

Chapter 22: How to Debug WDF Drivers

Listing 22-1: Boot.ini entries for kernel debugging over 1394

Chapter 23: PREfast for Drivers

Listing 23-1: Building PREfast samples-command window output

Listing 23-2: Building PREfast examples-prefast list command

Listing 23-3: Corrected code example that calls ExAcquireFastMutex at correct IRQL

Listing 23-4: Placement of PREfast annotations on a function

Listing 23-5: Alternative placement of PREfast annotations on function parameters

Listing 23-6: Two functions that show the difference between a string and an array of bytes

Listing 23-7: DRIVER_STARTIO function typedef declaration

Listing 23-8: Example of annotations for in-place substitution on a counted array of characters

Listing 23-9: Example of annotations for a buffer size that cannot be expressed as a simple expression

Listing 23-10: Example of ExAcquireResourceExclusiveLite with conditional annotation

Listing 23-11: Example of type annotations applied to KeWaitForMultipleObjects

Listing 23-12: Example of annotations for a function that must be called with a pointer to a nonpointer object

Listing 23-13: Example of annotations for functions that allocate and free memory

Listing 23-14: Example of annotations for a function that aliases memory

Listing 23-15: Example of annotations for functions that acquire and release a resource

Listing 23-16: Example of annotations for a function that acquires a global resource

Listing 23-17: Example of annotations for a function that acquires the critical region

Listing 23-18: Example of annotations for a function that might fail to acquire a resource

Listing 23-19: Example of annotations for a function that must hold the critical region

Listing 23-20: Example of annotations for a function that must never hold a spin lock

Listing 23-21: Example of annotations for functions that must not take or release a resource more than once

Listing 23-22: Example of a composite annotation for acquiring a spin lock

Listing 23-23: Example of annotation for a function of a specific function type class

Listing 23-24: Example of annotations that indicate where floating-point state is stored

Listing 23-25: Example of annotation for a function that uses floating point

Listing 23-26: Example of annotations for enforcing maximum IRQL

Listing 23-27: Example of annotations for overriding the default maximum IRQL

Listing 23-28: Example of annotations for saving and restoring IRQL

Listing 23-29: Example of annotations that prevent a function from raising IRQL

Listing 23-30: Example of annotations for IoGetDmaAdapter

Listing 23-31: Example of annotations for IoCreateDevice

Listing 23-32: Example of annotations for IoAttachDeviceToDeviceStack

Listing 23-33: Example of annotations for EngSaveFloatingPointState

Listing 23-34: Example of annotation test cases for a function

Listing 23-35: Example of code that exercises annotation test cases

Listing 23-36: Osrusbfx2.h with annotations

Chapter 24: Static Driver Verifier

Listing 24-1: SDV role types for Fail_driver6 callback functions

Listing 24-2: SDV function role types for Osrusbfx2 callback functions

Listing 24-3: Sdv-map.h file for Fail_driver6

Listing 24-4: PnP.sdv file for WDM drivers

Listing 24-5: SDV status messages for KMDF Request Buffer rules in Fail_driver6

Listing 24-6: Pass result for the FDODriver rule for Fail_Driver3

Listing 24-7: Fail result for FDOPowerPolicyOwnerAPI rule for Fail_Driver3