694430060 陳怡碩

Introduction to Plug and Play and Power Management in the Windows

Driver Foundation

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

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

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

NTSTATUSEvtPrepareHardware(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

NTSTATUSEvtDeviceD0Entry(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

BOOLEANEvtInterruptEnable(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

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