IWDFDevice2::AssignS0IdleSettings method (wudfddi.h)

Article
10/21/2021

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

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

Syntax

HRESULT AssignS0IdleSettings(
  [in] WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps,
  [in] DEVICE_POWER_STATE                    DxState,
  [in] ULONG                                 IdleTimeout,
  [in] WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Parameters

[in] IdleCaps

A WDF_POWER_POLICY_S0_IDLE_CAPABILITIES-typed enumerator that identifies the device's ability to wake itself after it is set to a low-power state, while the system remains in its working (S0) state.

[in] DxState

A DEVICE_POWER_STATE-typed enumerator that identifies the low device power state that the device will enter after the idle timeout period ends. DEVICE_POWER_STATE values are defined in wdm.h.

[in] IdleTimeout

The amount of time, in milliseconds, that the device will remain idle before the framework places it in the DxState-supplied low-power state. To use the framework's default idle timeout value, specify IdleTimeoutDefaultValue For more information, see the Remarks section.

[in] UserControlOfIdleSettings

A WDF_POWER_POLICY_S0_IDLE_USER_CONTROL-typed enumerator that indicates whether users have the ability to modify the device's idle settings.

[in] Enabled

A WDF_TRI_STATE-typed enumerator that indicates whether the device will be powered down if it remains idle and while the system power is at S0. This member can have one of the following values:

WdfTrue - Powering down is enabled.

WdfFalse - Powering down is disabled.

WdfUseDefault - Powering down is initially enabled by default; but if the UserControlOfIdleSettings parameter is set to IdleAllowUserControl, the user's setting or driver's INF file overrides the initial value.

If powering down is enabled, the device has a wake-up capability, and the idle timeout value expires, the framework calls the driver's IPowerPolicyCallbackWakeFromS0::OnArmWakeFromS0 callback function before the device enters a low-power state.

Return value

AssignS0IdleSettings returns S_OK if the operation succeeds. Otherwise, the method might return one of the following values:

Return code	Description
E_INVALIDARG	The caller specified an invalid value for an input parameter.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)	The calling driver is not the device's power policy owner.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	The DxState parameter specifies an invalid device power state, or the IdleCaps parameter indicates the device can wake itself, but the bus driver indicates the device cannot wake itself.

This method might return one of the other values that Winerror.h contains.

Remarks

The first time a driver calls AssignS0IdleSettings, the following actions occur:

The framework stores the values of all parameters.
If the UserControlOfIdleSettings parameter is set to IdleAllowUserControl and if the Enabled parameter is set to WdfUseDefault, the framework reads the registry to find out if the user has enabled powering down the device when it is idle.

During subsequent calls to AssignS0IdleSettings, the framework only stores the values of the DxState, IdleTimeout, and Enabled parameters. Also, the framework stores the value of the IdleCaps parameter subject to the following rules:

If the driver has ever specified IdleCanWakeFromS0 for the IdleCaps parameter's value in a previous call to AssignS0IdleSettings, it cannot subsequently change that value to IdleUsbSelectiveSuspend.
If the driver has ever specified IdleUsbSelectiveSuspend for the IdleCaps parameter's value in a previous call to AssignS0IdleSettings, it cannot subsequently change that value to IdleCanWakeFromS0.

The following rules apply to the value that you specify for the DxState parameter:

The value cannot be PowerDeviceD0.
For USB devices, the value cannot be PowerDeviceD0 or PowerDeviceD3.
If you specify DevicePowerMaximum, the framework uses the value that the kernel-mode driver for the device's bus supplied in the DeviceWake member of its WDF_DEVICE_POWER_CAPABILITIES structure.
If the value of the IdleCaps parameter is IdleCanWakeFromS0 or IdleUsbSelectiveSuspend, you cannot specify a device power state that is lower than the device power state in the DeviceWake member of the kernel-mode bus driver's WDF_DEVICE_POWER_CAPABILITIES structure. (In other words, if the bus driver's DeviceWake value is PowerDeviceD2, your function driver's DxState value cannot be PowerDeviceD3.)

If you specify IdleTimeoutDefaultValue for the IdleTimeout parameter, the timeout defaults to five seconds. You can examine the output from the !wudfext.wudfdevice and !wudfext.umdevstacks debugger extensions to see the effective settings and power references.

For information about registry entries that control a device's idle capabilities, see User Control of Device Idle and Wake Behavior in UMDF.

For more information about supporting a device's idle capabilities, see Supporting Idle Power-Down in UMDF-based Drivers.

Examples

The following code example is based on the UMDF version of the toaster sample. The example obtains the IWDFDevice2 interface and then calls AssignS0IdleSettings.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
    //
    // The toaster device is virtual, so we tell the framework that the 
    // device cannot wake if it sleeps while the system is in S0. The device 
    // can return to D0 only when the driver stack receives an I/O request.
    //
    hr = pIWDFDevice2->AssignS0IdleSettings(IdleCannotWakeFromS0,
                                            PowerDeviceD3,
                                            IDLEWAKE_TIMEOUT_MSEC,
                                            IdleAllowUserControl,
                                            WdfTrue);
    }
...
    SAFE_RELEASE(pIWDFDevice2);

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.9
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Share via