WdfDeviceStopIdle method

[Applies to KMDF and UMDF]

The WdfDeviceStopIdle method informs the framework that the specified device must be placed in its working (D0) power state.

Syntax

NTSTATUS WdfDeviceStopIdle(
  [in]  WDFDEVICE Device,
  [in]  BOOLEAN WaitForD0
);

Parameters

Device [in]

A handle to a framework device object.

WaitForD0 [in]

A Boolean value that indicates when WdfDeviceStopIdle will return. If TRUE, it returns only after the specified device has entered the D0 device power state. If FALSE, the method returns immediately.

Return value

If the operation succeeds, WdfDeviceStopIdle returns STATUS_SUCCESS. If the driver calls WdfDeviceStopIdle when the device is in its working (D0) state, the method returns STATUS_SUCCESS, but does not initiate a power transition.

Additional return values include:

The method might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

If your device can enter a low-power state when it becomes idle, your driver might have to occasionally call WdfDeviceStopIdle to bring the device back to its working (D0) state or to prevent it from entering a low-power state.

Your driver does not have to call WdfDeviceStopIdle when a device is idle and the framework places an I/O request in the device's power-managed I/O queue. Additionally, your driver does not have to call WdfDeviceStopIdle when a device is idle and it detects a wake signal. In both of these cases, the framework requests the bus driver to restore the device's power state to D0.

Although drivers typically do not need to call WdfDeviceStopIdle when handling I/O requests that they obtain from a power-managed I/O queue, the call is allowed. However, drivers must not set the WaitForD0 parameter to TRUE when handling I/O requests from a power-managed I/O queue.

Your driver does have to call WdfDeviceStopIdle if it must access the device because of a request that the driver has received outside of a power-managed I/O queue. For example, your driver might support a driver-defined interface or a WMI request that requires accessing the device. In this case, you must ensure that the device is in its working state before the driver accesses the device, and that the device remains in its working state until the driver has finished accessing the device.

Calling WdfDeviceStopIdle forces the device into its working (D0) state, if the system is in its working (S0) state. The device remains in its working state until the driver calls WdfDeviceResumeIdle, at which point the framework can place the device in a low-power state if it remains idle.

Do not call WdfDeviceStopIdle before the framework has called the driver's EvtDeviceD0Entry callback function for the first time.

A call to WdfDeviceStopIdle can restore an idle device to its working state only if the system is in its working (S0) state. If the system is entering a low-power state when a driver calls WdfDeviceStopIdle with the WaitForD0 parameter set to TRUE, the function does not return until the system returns to its S0 state.

Every successful call to WdfDeviceStopIdle must eventually be followed by a call to WdfDeviceResumeIdle, or else the device will never return to a low-power state if it again becomes idle. Calls to WdfDeviceStopIdle can be nested, so the number of calls to WdfDeviceResumeIdle must equal the number of calls to WdfDeviceStopIdle. Do not call WdfDeviceResumeIdle if a call to WdfDeviceStopIdle fails.

If the system enters a low-power state after WdfDeviceStopIdle returns, the device also enters a low-power state. When the system returns to its working (S0) state, the device also returns to its working (D0) state. The power reference from the call to WdfDeviceStopIdle remains active and prevents the device from entering a low-power state until there is a matching call to WdfDeviceResumeIdle.

For more information, see Supporting Idle Power-Down.

If WaitForD0 is TRUE, WdfDeviceStopIdle must be called at IRQL = PASSIVE_LEVEL. If WaitForD0 is FALSE, this method must be called at IRQL <= DISPATCH_LEVEL.

Examples

In the following code example, WdfDeviceStopIdle returns after the specified device has entered the D0 device power state.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Requirements

See also

WdfDeviceResumeIdle

Send comments about this topic to Microsoft