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

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

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

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

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.

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.

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

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.

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

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

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

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.

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

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

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.

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

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

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

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

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

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

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

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

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)

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)

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;

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.

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.

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.

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

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

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

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

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

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

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

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

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

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

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