Chris Cant - Writing Windows WDM Device Drivers

PoSetPowerState(dx->fdo, DevicePowerState, NewState);

}

Each Wdm2 I/O request dispatch routine must check that the Wdm2 device is powered up. Listing 10.8 shows how Wdm2Write calls PowerUpDevice to power the device up if necessary by calling SendDeviceSetPower . Finally, PowerUpDevice resets the idle counter using PoSetDeviceBusy .

Listing 10.8 Dispatch routine power handling

NTSTATUS Wdm2Write(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

// …

NTSTATUS status = PowerUpDevice(fdo);

if (!NT_SUCCESS(status)) return CompleteIrp(Irp, status, 0);

// …

}

NTSTATUS PowerUpDevice(IN PDEVICE_OBJECT fdo) {

PWDM2_DEVICE_EXTENSION dx = (PWDH2_DEVICE_EXTENSION)fdo->DeviceExtension;

// If need be, increase power

if (dx->PowerState>PowerDeviceD0) {

NTSTATUS status = SendDeviceSetPower(dx, PowerDeviceD0);

if (!NT_SUCCESS(status)) return status;

}

// Zero our idle counter

if (dx->PowerIdleCounter) PoSetDeviceBusy(dx->PowerIdleCounter);

return STATUS_SUCCESS;

}

You can investigate some of Wdm2's power capabilities by inspecting the checked build DebugPrint output using the DebugPrint Monitor. Make sure that you have installed the DebugPrint driver and the checked build of the Wdm2 driver.

Under W2000, the idle detection process can be seen working. After 60 seconds on my AC powered desktop system, the Power Manager sends a Set device Power IRP to power down the device to D3. If you then run the Wdm2TestWin32 application, the first read or write powers the Wdm2 device back up to D0.

On the same computer running Windows 98, no idle Set device Power IRPs were seen. This must be another manifestation of the bug described earlier. I changed the code so that Wdm2 started in a powered off state. When Wdm2Testwas run, the Set device Power IRP (to power the device up) completed successfully, but the driver was not sent the Power IRP. This is why SendDeviceSetPower shown in Listing 10.5 checks that the device has really changed power state, and forces the change if necessary.

I cannot explain why Set Power IRPs are not received by the Wdm2 driver in Windows 98. Perhaps the idle detection process is working, but the Set device IRP is simply not seen by the driver.

If your system can sleep or hibernate then use the Wdm2Power application to test these features.

Another piece of the Power Management puzzle is the IRP_MN_QUERY_CAPABILITIES Plug and Play IRP minor function code. The bus driver usually fills in a DEVICE_CAPABILITIES structure. Several of these fields relate to Power Management. Function or filter drivers can inspect or modify the values set by the bus driver.

Listing 10.9 shows how PnpQueryCapabilitiesHandler handles the Query Capabilities PnP IRP for Wdm2. It first forwards the IRP down the stack and waits for it to complete. It then alters the DEVICE_CAPABILITIES structure, if necessary.

The DeviceState field is an array that indicates the corresponding device power state for each system power state. Or more precisely, it specifies the most powered state that a device can be in at a system power level. For example, when the system is fully on in S0, the device can be fully on in D0 or it may have idled into D3.

PnpQueryCapabilitiesHandler ensures that the correct "most powered device state" is specified by the bus driver. The SetMostPoweredState macro checks to see if a device state has been set and ups the DeviceState entry if appropriate.

Listing 10.9 PnpQueryCapabilitiesHandler routine

#define SetMostPoweredState(SystemState, OurDeviceState) \

dps = deviceCapabilities->DeviceState[SystemState]; \

if (dps==PowerDeviceUnspecified || dps>OurDeviceState) \

deviceCapabilities->DeviceState[SystemState] = OurDeviceState

NTSTATUS PnpQueryCapabilitiesHandler(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

NTSTATUS status = ForwardIrpAndWait(fdo, Irp);

if (NT_SUCCESS(status)) {

PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

PDEVICE_CAPABILITIES deviceCapabilities;

deviceCapabilities = IrpStack-Parameters->DeviceCapabilities.Capabilities;

#if DBG

for (int ds=PowerSystemWorking; ds

DebugPrint("Capabilities from bus: DeviceState[%d]=%d",

ds, deviceCapabilities->DeviceState[ds]);

#endif

DEVICE_POWER_STATE dps;

SetMostPoweredState(PowerSystemWorking, PowerDeviceD0); // S0

SetMostPoweredState(PowerSystemSleeping1, PowerDeviceD3); // S1

SetMostPoweredState(PowerSystemSleeping2, PowerDeviceD3); // S2

SetMostPoweredState(PowerSystemSleeping3, PowerDeviceD3); // S3

SetMostPoweredState(PowerSystemHibernate, PowerDeviceD3); // S4

SetMostPoweredState(PowerSystemShutdown, PowerDeviceD3); // S5

}

return CompleteIrp(Irp, status, Irp->IoStatus.Information);

}

The bus driver for the Wdm2 device sets different values in DeviceState in Windows 98 and Windows 2000 Beta 2, as shown in Table 10.4. Windows 98 sets the most powered device state for S0–S4 to D0 and for S5 to D3. The most powered values for Wdm2 do not alter these values. In contrast, Windows 2000 Beta 2 sets the most powered device state for S1-S3 to D3 but does not set values for the other system states. PnpQueryCapabilitiesHandler will, therefore, modify DeviceState tor S0, S4, and S5.

Table 10.4 DeviceState values

The SystemWake and DeviceWake fields in the DEVICE_CAPABILITIES structure indicate the lowest powered state from which a device can wake the system. These fields are set to PowerSystemUndefined (0) if the device cannot wake the system. If necessary, alter the values that the bus driver has set.

The D1Latency, D2Latency, and D3Latency fields indicate the approximate time in 100-microsecond units that the device takes to return to the fully on DO state for each sleeping state. Increase the values set by the bus driver, if necessary.

Finally, note that another PnP IRP, IRP_MN_QUERY_RELATIONS, has a PowerRelations subtype that asks for the PDOs of the devices that are related to the current device. These other devices are powered down when this device powers down.

The basic idea of IRP_MN_WAIT_WAKE Power IRP is quite simple. It lets devices wake the system up from a sleeping state. A classic example is letting an incoming call from a modem wake up the system. Alternatively, a soft power on/off switch could power the system up when it is pressed.