Chris Cant - Writing Windows WDM Device Drivers

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

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.

Table 10.2 Device power states

Both the state values increase from 1 the sleepier they are.

A device need not support all the device states. DO for on and D3 for off are a basic minimum. A device is not limited in its state transitions, so a change from D1 to D3 is possible.

Later, I describe how each device (or its bus driver) provides a table for device states for each system state.

A driver's Power Management routines revolve around the Power IRP, IRP_MJ_POWER, by both handling it and generating it when necessary. There are four minor function code variants of the Power IRP shown in Table 10.3.

Table 10.3 IRP_MN_POWER minor function codes

The Power Manager maintains a separate internal queue of Power IRPs. This ensures that there is only one Set System Power IRP being processed in the system. It also ensures that there is only one Set Device Power IRP running for each device. These rules ensure that power transitions are handled smoothly. As each device is powered up, it may require an inrush of energy. Handling Power IRPs one at a time ensures that the peak power required is kept as low as possible.

As the Power Manager has its own queue of IRPs, do not use the standard I/O Manager routines when handling IRPs. Use PoCallDriver instead of IoCallDriver to call the next driver down the stack.

You must tell the Power Manager when you have finished processing a power IRP so that it can start the next. If you are simply passing an IRP down the stack (with no completion routine) then you should call the PoStartNextPowerIrp function before you skip or copy the current IRP stack location. If you use a completion routine, it must also usually call PoStartNextPowerIrp . Full examples of these calls are given later.

A Query Power IRP request is sent to see if a state change is acceptable to all the drivers in the device stack. A Set Power IRP is then issued to actually make the change.

You can send yourself a Set Device Power State IRP at any time. However, only the Power Manager can send Set System Power State IRPs. To process a Set System Power State IRP, you must send yourself a Set Device Power State IRP. That's right — you must ask for a Power IRP to be sent to the top of your device stack.

Handling Device Power IRPs

Handling a Set Device Power State is relatively straightforward. You must power down your device before all the lower drivers. Conversely, power your device up after all the lower drivers have powered up. This means setting a completion routine and doing the power up there.

Handling System Power IRPs

Handling a Set System Power State is a different kettle of fish. If you receive a Set System Power IRP, you must first determine the equivalent device power state. The Wdm2 driver is put in the fully on device state D0 for the fully on system state S0. For all other system states, the Wdm2 device state is fully off, D3.

If the current device state is not the same as the required device state, you must act to change it. As before, powering down requires that you change the device state before you pass the Set System Power State down to the lower drivers. Power up after all the lower drivers have had their say.

You must change device power state by issuing a Set Device Power State IRP to yourself. You must then wait for this IRP to complete. You can then continue processing the Set system state IRP.

Same System Power

Suppose you receive a Set System Power State IRP. You must work out the corresponding device power state. If your device is already at this power level, then all you need to do is pass the IRP to the lower drivers.

System Powering Down

If you decide that your device needs to power down, then you must send yourself a Set Device Power IRP before you pass down the system IRP. Figure 10.2 illustrates this scenario. It assumes that the first Query Set System Power State IRP has completed OK, at (1).

In the figure, the Set System State IRP handler decides that it must power its device down at (2). It sends a Set Device State IRP to itself, and sets a completion routine so that it knows when this second IRP has been completed.

In due course, your driver will receive the Set Device State IRP (that you sent yourself) at (3). Your driver will decide again that it must power down. It does this at (4) and then sends the IRP down to the lower drivers at (5).

When the Set Device State IRP has been processed by all the lower drivers, the completion routine is called at (6). This signals to the original IRP handler that it can continue, at © again. All this has to do is pass the IRP down to the lower drivers at (7).

Figure 10.2 Power down system processing

System Powering Up

In contrast, Figure 10.3 shows what might happen when your device has to power up to get to the required new system power state. First, a Query Power IRP is sent at (1) asking if a new system state is OK. Then a Set Power IRP is issued for the system power state. The driver determines that it must power up its device. It sets a completion routine and passes the IRP to the lower drivers at (2).