WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure (wdfdevice.h)
[Applies to KMDF and UMDF]
The WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure contains driver-supplied information about a device's ability to wake itself and the system, when both are in a low-power state.
Syntax
typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
ULONG Size;
DEVICE_POWER_STATE DxState;
WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
WDF_TRI_STATE Enabled;
BOOLEAN ArmForWakeIfChildrenAreArmedForWake;
BOOLEAN IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;
Members
Size
The size, in bytes, of this structure.
DxState
A DEVICE_POWER_STATE-typed enumerator that identifies the low device power state that the device will enter when the system power state drops to a wakeable low-power state. The value of DxState cannot be PowerDeviceD0. DEVICE_POWER_STATE values are defined in wdm.h.
UserControlOfWakeSettings
A WDF_POWER_POLICY_SX_WAKE_USER_CONTROL-typed enumerator that indicates whether users have the ability to modify the device's wake settings.
Enabled
A WDF_TRI_STATE-typed enumerator that indicates whether the device can wake the system (that is, restore the system to S0) when the system is in a low-power state. This member can have one of the following values:
WdfTrue - Waking the system is enabled.
WdfFalse - Waking the system is disabled.
WdfUseDefault - Waking the system is initially enabled by default; but if the UserControlOfWakeSettings member is set to WakeAllowUserControl, the user's setting or driver's INF file overrides the initial value.
If waking the system is enabled and the system is about to enter a low-power state, the framework calls the driver's EvtDeviceArmWakeFromSx or EvtDeviceArmWakeFromSxWithReason callback function before the device enters a low-power state.
ArmForWakeIfChildrenAreArmedForWake
A Boolean value that, if set to TRUE, indicates that a parent device's ability to wake itself and the system should be enabled when this ability is enabled for the device's child devices. For more information, see the following Remarks section. This member is available in version 1.7 and later versions of KMDF.
IndicateChildWakeOnParentWake
A Boolean value that, if set to TRUE, indicates that the framework will provide wake-up status to child devices if a parent device detects a wake-up signal. For more information, see the following Remarks section. This member is available in version 1.7 and later versions of KMDF.
Remarks
The WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure is used as input to WdfDeviceAssignSxWakeSettings.
To initialize its WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure, your driver should call WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT.
The first time a driver calls WdfDeviceAssignSxWakeSettings, the following actions occur:
- The framework stores the values of all WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure members.
- If the UserControlOfWakeSettings member is set to WakeAllowUserControl and if the Enabled member is set to WdfUseDefault, the framework reads the registry to find out if the user has enabled waking the system.
- Stores the value of the UserControlOfWakeSettings member.
- Looks for a user setting in the registry, if the value of the Enabled member is WdfUseDefault.
- The value cannot be PowerDeviceD0.
- If you specify PowerDeviceMaximum, the framework uses the value that the driver for the device's bus supplied in the DeviceWake member of its WDF_DEVICE_POWER_CAPABILITIES structure.
- You cannot specify a device power state that is lower than the device power state in the DeviceWake member of the 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 the device that the WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure describes is a parent device, the driver for the parent device can use the ArmForWakeIfChildrenAreArmedForWake and IndicateChildWakeOnParentWake members as follows:
-
If the driver sets the ArmForWakeIfChildrenAreArmedForWake member to TRUE, the framework calls the driver's EvtDeviceArmWakeFromSx or EvtDeviceArmWakeFromSxWithReason callback function when a child device's wake ability is enabled, even if the parent device's wake ability is not enabled.
To reduce power consumption, you might not want to enable your device's wake ability unless a child device that also supports a wake ability is plugged in. If your driver sets the ArmForWakeIfChildrenAreArmedForWake member to TRUE, the Enabled member's values have the following meanings:
- If Enabled is WdfFalse, the framework enables your driver's wake ability only if a child device's wake ability is enabled.
- If Enabled is WdfTrue, the framework always enables your driver's wake ability, whether your device has wake-enabled child devices or not.
- If Enabled is WdfUseDefault and UserControlOfWakeSettings is WakeAllowUserControl, users can control whether your device is always wake-enabled or if it is wake-enabled only when your device has child devices that are wake-enabled.
- If the driver sets the IndicateChildWakeOnParentWake member to TRUE, the framework calls the EvtDeviceWakeFromSxTriggered callback function in the parent device's driver and in the driver for each wake-enabled child device. If the driver sets this member to FALSE, the framework calls the EvtDeviceWakeFromSxTriggered callback function in the parent device's driver only. Your driver should set IndicateChildWakeOnParentWake to TRUE if the drivers for your device's children must examine hardware to determine why the system was awakened.
Requirements
| Requirement | Value |
|---|---|
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfdevice.h (include Wdf.h) |
See also
EvtDeviceArmWakeFromSxWithReason
WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for