Writing Windows WDM Device Drivers

User mode applications might be interested in receiving power events. If an application does background processing, it should stop this work if the system goes to sleep. Alternatively, it can insist that the system does not sleep.

Wdm2Power Application

The Wdm2Power application in the Wdm2Power directory of the book software shows how to handle the following aspects of Power Management in Win32.

• Capturing WM_POWERBROADCAST messages

• Attempting to suspend or hibernate the system with SetSystemPowerState.

• Getting the system power status using GetSystemPowerStatus.

• Getting the hard disk status using GetDevicePowerState.

You may find Wdm2Power useful when testing the Power Management capabilities of your driver. Figure 10.1 shows how Wdm2Power looks in Windows 98 on a desktop system.

I found that it was necessary to alter some VC++ 5 settings to be able to compile Wdm2Power. I needed to use the Platform SDK standard include files and libraries. This meant altering the Directories in the Tools+Options menu. I had to put the Platform SDK include directory at the head of the 'Include files' directories listing (i.e., D: MSSDKINCLUDE on my PC). Similarly, I had to put its library directory at the head of the 'Library files' directories listing (e.g., D:MSSDKLIB). This may effect your other projects, so change these settings back afterwards.

Figure 10.1 Example Wdm2Power output

The system broadcasts WM_POWERBROADCAST messages to indicate various power management events or requests. In the Wdm2Power MFC dialog box application these are handled in the OnPowerBroadcast method in Wdm2PowerDlg.cpp. It simply adds the event information to the window list box.

Both the Suspend and Hibernate options eventually call the SetSystemPowerState function in the SuspendOrHibernate dialog method. In W2000 you have to enable the shutdown privilege for this process. The Hibernate option is only available in Windows 2000.

Wdm2Poiver sets a timer that calls its GetPowerStatus method every second. This calls the GetSystemPowerStatus function to get the system power state and GetDevicePowerState to determine if Wdm2Power's disk has been spun down. On my system, GetDevicePowerState always returned FALSE, which I presume means that the file system does not handle the IOCTL command IOCTL_GET_DEVICE_POWER_STATUS.

Win32 applications can also ask that the system not be put to sleep using the SetThreadExecutionState function. Alternatively, they can request that the lowest latency sleep be used using RegisterWakeupLatency. Finally, they can request that the system wake up at a certain time or in response to a device event, such as a modem ring.

Battery Miniclass Drivers

The Power Manager uses battery miniclass drivers to provide an interface to batteries. These miniclass drivers must fit in with the specification given in the DDK documentation. For example, it must register its various callback entry points using BatteryClassInitializeDevice.

Battery miniclass drivers must include routines to support PnP and to support battery management and monitoring.

System Power Policies

The rest of this chapter looks at how device drivers handle Power Management. Some classes of device ought to have certain Power Management characteristics. These details are found in the Device Class Power Management specification.

System power states indicate the overall energy usage of a whole system, while a device power state says how much energy an individual device is using. Even though the system may be fully powered up, a device can power itself down. For example, if a battery-operated computer is fully on but the hard disk is not being used, the disk driver may reasonably decide to power the disk down to save energy. Conversely, a sleeping computer may keep its modem powered up if it is waiting for incoming faxes.

System and Device States

Windows defines six system power states and four device power states. Please be very clear about whether you are referring to system or device power states.

A POWER_STATE variable represents either a system or device power state. The POWER_STATE typedef is a union of the two enum typedefs, SYSTEM_POWER_STATE and DEVICE_POWER_STATE.

typedef union _POWER_STATE {
 SYSTEM_POWER_STATE SystemState;
 DEVICE_POWER_STATE DeviceState;
} POWER_STATE, *PPOWER__STATE;

System Power States

Table 10.1 shows the system power states along with the SYSTEM_POWER_STATE enum names and values. Sleeping state S1 has the lowest latency so the system can return to the fully on state in the quickest time possible. States S2 and S3 gradually increase power up latency and decrease power consumption.

Table 10.1 System power states

ACPI State	Description	Enum name
S0	Working/Fully on	PowerSystemWorking(1)
S1	Sleeping	PowerSystemSleeping1(2)
S2	Sleeping	PowerSystemSleeping2(3)
S3	Sleeping	PowerSystemSleeping3(4)
S4	Hibernating: Off, except for trickle current to the power button and similar devices.	PowerSystemHibernate(5)
S5	Shutdown/Off	PowerSystemShutdown(6)

Windows moves to and from only S0. There are never changes between the states S1 to S5 (e.g., from S4 to S2). Windows always assumes that it can power up to S0, so it does not have to ask drivers for permission (using the IRP_MN_QUERY_POWER request).

The IRP stack Parameters.Power.ShutdownType value gives extra information about system state changes. It is particularly useful for transitions to S5. PowerActionShutdownReset indicates a reboot while PowerActionShutdownOff means the computer is being switched off.

Device Power States

Table 10.2 shows the available device power states along with the DEVICE_POWER_STATE enum names and values. Again, state D1 has lower latency than D2.