WdfDeviceAssignS0IdleSettings function (wdfdevice.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfDeviceAssignS0IdleSettings method provides driver-supplied information that the framework uses when a device is idle and the system is in its working (S0) state.

Syntax

NTSTATUS WdfDeviceAssignS0IdleSettings(
  [in] WDFDEVICE                              Device,
  [in] PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS Settings
);

Parameters

[in] Device

A handle to a framework device object.

[in] Settings

A pointer to a caller-supplied WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure.

Return value

If the operation succeeds, WdfDeviceAssignS0IdleSettings returns STATUS_SUCCESS. Additional return values include:

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	The calling driver is not the device's power policy owner.
STATUS_INVALID_PARAMETER	An invalid Settings value is detected.
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure is incorrect.
STATUS_POWER_STATE_INVALID	This value is returned if one of the following occurs: The WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure contains an invalid device power state. The IdleCaps member of the WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure indicates the device can wake itself, but the bus driver indicates the device cannot wake itself. Starting in KMDF version 1.11 running on Windows 8, the framework checks if the system's firmware can handle a wake signal while the system is in its fully on (S0) power state. If the machine fails this check, WdfDeviceAssignS0IdleSettings returns STATUS_POWER_STATE_INVALID, and the device remains in its fully on (D0) power state as long as the system remains in S0. In this case, the driver should not return an error status value from EvtDriverDeviceAdd or any other runtime callback. At most, the driver might log an error indicating that the device will consume more power than it normally would.

The method might return other NTSTATUS values.

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

Remarks

If the driver sets the IdleTimeoutType member of WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS to SystemManagedIdleTimeout or SystemManagedIdleTimeoutWithHint, it must call WdfDeviceAssignS0IdleSettings before returning from EvtDeviceD0Entry. Typically, a driver first calls WdfDeviceAssignS0IdleSettings from EvtDriverDeviceAdd.

Additional calls to WdfDeviceAssignS0IdleSettings can be made at any time. However, after the driver sets the value of the IdleTimeoutType member in its first call to WdfDeviceAssignS0IdleSettings, it must not change this value in later calls to this method.

If the driver registers for asynchronous notifications in EvtDriverDeviceAdd (for example by calling PoRegisterPowerSettingCallback or IoRegisterPlugPlayNotification), the driver must not subsequently call WdfDeviceAssignS0IdleSettings from within the driver callback routine that it registered.

For more information, see Supporting Idle Power-Down.

Examples

The following code example initializes a WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure, sets an idle time-out value of 10 seconds, and calls WdfDeviceAssignS0IdleSettings.

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS  idleSettings;
NTSTATUS  status = STATUS_SUCCESS;

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT(
                                           &idleSettings,
                                           IdleCanWakeFromS0
                                           );
idleSettings.IdleTimeout = 10000;

status = WdfDeviceAssignS0IdleSettings(
                                       device,
                                       &idleSettings
                                       );
if (!NT_SUCCESS(status)) {
    return status;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfdevice.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), FDOPowerPolicyOwnerAPI(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), NonFDONotPowerPolicyOwnerAPI(kmdf)

Share via