1. Introduction to Plug and Play and Power Management in the Windows Driver Foundation
陳怡碩

2. Abstract
The Windows Driver Foundation (WDF) defines a new model for developing device drivers for the Microsoft® Windows® family of operating systems
This paper provides an introduction to how drivers implement Plug and Play and Power Management features using the kernel-mode driver framework that is part of WDF

3. Introduction(一) The Windows Driver Foundation comprises two parts:
kernel-mode driver framework
user-mode driver framework
The major goal of the Windows Driver Foundation (WDF) :
Easy to develop
The freedom necessary to support

4. Introduction(二) Kernel mode goal
provided by its implementation of Plug and Play (PnP) .
power management.

5. A Brief Review of WDF Concepts(一)
Execution of a framework-based driver begins at DriverEntry
A WDF driver initializes and instantiates its WDFDRIVER object.
A framework-based driver initializes and instantiates a WDFDEVICE object
a framework-based driver is called is EvtDeviceAdd.

6. A Brief Review of WDF Concepts(二)
A driver also declares its I/O request queuing model, and the queues it will use, within its EvtDeviceAdd routine
A framework-based driver that supports hardware that is capable of interrupting initializes its WDFINTERRUPT object.

7. Implementing PnP & Power Management（一）
Windows Driver Foundation implements a fully integrated model for PnP and power management
Unlike WDM, PnP and power management are not implemented separately in a WDF driver
Advantages：
Presents a single, streamlined set of interfaces
Eliminates the need for redundant driver code

8. Implementing PnP & Power Management（二）
example driver types
A description of the type of driver and the PnP and power management features that the driver implements.
A description of the framework functions that need to be called or event callbacks that the driver needs to implement to support the desired PnP and power management features.
Example code showing the implementation of those features.
The framework takes in response to various example PnP and power events for this driver type.

9. Power Policy in WDF Drivers
The device power state (D state) closely reflects the system’s power state (S state)
The management of D states for a device is called “power policy”
A driver other than a function driver can indicate to WDF that it is the power policy owner for its device by issuing a function call during initialization

10. Software-Only Drivers
A software-only driver is a driver that does not control any hardware
A software-only driver can be either a root-enumerated function driver or a filter driver

11. Implementing Framework-Based Software-Only Drivers
Software-only WDF drivers demonstrate the dramatic difference between the framework and WDM
Software-only drivers typically utilize the default PnP and power management handling provided by the framework
Any arriving PnP or power events are automatically managed by the framework

12. WDFQUEUE Handling for Software-Only Drivers
By default, the framework implements power management for all WDFQUEUE objects
When a WDFQUEUE is power managed, requests are dispatched from the queue to the driver’s I/O processing callback events only when the device’s hardware is available
Software-only drivers do not access any device hardware. Therefore, software-only drivers, especially filter drivers, should typically disable power management for all their queues.

13. Example PnP and Power Code for a Software-Only Driver
A basic EvtDeviceAdd function for a software-only driver
This function contains two PnP or power management features :
Support for the optional WDFDEVICE cleanup event
The driver’s disabling power management support for its one WDFQUEUE
P.6-P.9

14. Framework Actions for a Software-Only Driver
In the software-only driver, almost all PnP/PM operations are handled by the framework.
The framework will automatically grant operation system requests that arrive at the driver fort PM operations
Driver doesn’t control any hardware, it doesn’t need to provide any additional event handler callbacks

15. Hardware Function Drivers
The framework handles most of the PnP/PM tasks for hardware function drivers in the same way that it handles those tasks for software-only drivers.

16. Implementing Hardware Function Drivers (一)
That is, the driver must determine what I/O ports, memory mapped addresses
Interrupts are used to communicate with its device, store that information for later use, and map any memory-based resources into kernel virtual address space

17. Implementing Hardware Function Drivers (二)
A driver that supports hardware must initialize its device to a known state every time the device transitions to D0, including during system startup
Most drivers that support hardware must manage interrupts from their devices, including enabling and disabling device interrupts when requested by the framework
The framework will automatically stop dispatching I/O requests from those queues to the driver whenever its device’s hardware is not accessible

18. Hardware Resource Identification and Tear-Down
During initialization, the framework calls a driver’s EvtPrepareHardware callback with the collection of hardware resources that have been assigned to the device
When a device relinquishes its hardware resources, the framework calls EvtReleaseHardware to request the driver to tear down any software state
that was previously established in EvtPrepareHardware

19. Device Power-Up Initialization and Power-Down Tear-Down
Each time a device enters D0, the framework calls the driver for that device at its EvtDeviceD0Entry event callback
The driver’s EvtDeviceD0Entry is called after the driver’s EvtPrepareHardware function has been called
Each time a device is about to leave D0, the framework calls the device’s driver at its EvtDeviceD0Exit event callback

20. Interrupt Support
A driver that supports interrupts from its device will create a WDFINTERRUPT object during EvtDeviceAdd processing
The driver specifies interrupt enable and interrupt disable event callback functions by filling in the EvtInterruptEnable and EvtInterruptDisable members

21. WDFQUEUE Management in Hardware Function Drivers (一)
WDFQUEUE objects are power managed by default by the framework
when a WDFQUEUE is power managed by the framework, requests are dispatched from that queue to the driver’s I/O processing callback events only when the device’s hardware is accessible and powered to D0

22. WDFQUEUE Management in Hardware Function Drivers (二)
The driver therefore sorts requests into two :
WDFQUEUE：A power-managed WDFQUEUE for read and write requests
WDFQUEUE：A non–power-managed WDFQUEUE for device control requests

23. Example PnP and Power Code for a Hardware Function Driver
EvtPrepareHardware and EvtReleaseHardware callbacks
EvtDeviceD0Entry and EvtDeviceD0Exit callbacks
Interrupt handling, including creating a WDFINTERRUPT object and support for EvtInterruptEnable and EvtInterruptDisable callbacks
P.12 ~ P.17

24. Framework Actions for a Simple Hardware Function Driver (一)
Almost all of PnP and power management is done for this driver by the framework
Whenever a set of hardware resources is assigned to a device, its driver’s EvtPrepareHardware function is called
NTSTATUS EvtPrepareHardware(WDFDEVICE Device WDFCOLLECTION Resources, WDFCOLLECTION ResourcesTranslated)

25. Framework Actions for a Simple Hardware Function Driver (二)
Each time a device is about to enter D0, the framework calls the driver’s EvtDeviceD0Entry function
NTSTATUS EvtDeviceD0Entry(WDFDEVICE Device,WDF_POWER_DEVICE_STATE PreviousState)

26. Framework Actions for a Simple Hardware Function Driver (三)
The value for the parameter which represents the previous state is an enum, taken from the following list :
typedef enum _WDF_POWER_DEVICE_STATE { WdfPowerDeviceUnspecified = 0, WdfPowerDeviceD0, WdfPowerDeviceD1, WdfPowerDeviceD2, WdfPowerDeviceD3, WdfPowerDeviceStateD3Final, WdfPowerDevicePrepareForHibernation,
WdfPowerDeviceMaximum } WDF_POWER_DEVICE_STATE,*PWDF_POWER_DEVICE_STATE;

27. Framework Actions for a Simple Hardware Function Driver (四)
If the EvtDeviceD0Entry callback returns success, the framework next connects the driver’s ISR to device interrupts and enables interrupts on the device by calling the driver’s EvtInterruptEnable function
BOOLEAN EvtInterruptEnable(WDFINTERRUPT Interrupt, WDFDEVICE Device)
After it returns from EvtInterruptEnable, the device is ready for use.

28. Device Startup and Initialization
1. EvtDevicePrepareHardware is called by the framework.
2. EvtDeviceD0Entry is called by the framework.
3. The framework connects the device’s ISR to interrupts from the device.
4. EvtInterruptEnable is called by the framework at DIRQL.
5. EvtDeviceD0EntryPostInterruptsEnabled is called by the framework at IRQL PASSIVE_LEVEL.
6. The framework releases any WDFQUEUEs that are power managed.

29. Remove a Device 1. The framework holds all power-managed WDFQUEUEs.
2. EvtDeviceD0ExitPreInterruptsDisabled is called by the framework at IRQL PASSIVE_LEVEL.
3. EvtInterruptDisable is called by the framework at DIRQL.
4. The framework disconnects the driver’s ISR from the device.
5. EvtDeviceD0Exit is called by the framework.
6. EvtDeviceReleaseHardware is called by the framework.

30. Driver writers might be particularly interested in two target states that the framework can pass into a driver’s EvtDeviceD0Exit event callback：
WdfPowerDevicePrepareForHibernation
WdfPowerDeviceStateD3Final

31. Hardware Function Drivers with Idle Support
The framework handles most of the complex work involved in implementing PnP and power management

32. Implementing Device Power-Down Idle Support (一)
A framework driver indicates that it will support idle within its EvtDeviceAdd function
Whether device power-down on idle support is enabled for the device
The amount of time without receiving an I/O request before the device is considered idle
The device power state to which the device should be transitioned when it is idled

33. Implementing Device Power-Down Idle Support (二)
It’s controlled by the field Enabled and the default is WdfDefault
The driver sets this value into the IdleTimeout field
The driver sets this value in the DxState field

34. Implementing Device Power-Down Idle Support (三)
Wether the user can control idle policy or not is determined by the setting of the UserControlOfIdleSettings field
IdleAllowUserControl (the default)
IdleDoNotAllowUserControl

35. Implementing Device Power-Down Idle Support (四)
Device idle policy can be changed at any time by the driver, after its initial call to WdfDeviceUpdateS0IdleSettings in its EvtDeviceAdd function
A driver can also indicate to the framework that a device has entered or exited a state in which the device may not be idled by using the WdfDevicePowerReference and WdfDevicePowerDereference functions

36. Implementing Device Power-Down Idle Support (五)
After IdleTimeout milliseconds pass and no I/O requests are active on the device, the framework transitions the device to the lower-power state the driver indicated in its last call to WdfDeviceUpdateS0IdleSettings

37. Implementing Device Power-Down Idle Support (六)
The framework returns the device to D0 whenever one of the following occurs :
A new I/O request arrives at any of the device’s power-managed queues
The driver calls WdfDevicePowerReference
The driver disables idle support by calling WdfDeviceUpdateS0IdleSettings

38. Choosing Appropriate Idle Times and Idle States
A framework-based driver can avoid its devices prematurely entering the idle state by increasing the IdleTimeout value and calling WdfDeviceUpdateS0IdleSettings each time the device becomes non-idle

39. Example PnP and Power Code for Supporting Device Idle
This driver adds support for device idle by initializing WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure and calling WdfDeviceUpdateS0IdleSettings
P.22 -P.26

40. Framework Actions Supporting Device Idle
The framework keeps a count of I/O activity on all power-managed WDFQUEUEs owned by each WDFDEVICE
While the device is idling in its low-powered state, the framework will automatically transition the device back into D0 whenever the count of I/O activity on any of the device’s power-managed queues becomes non-zero