EvtDeviceArmWakeFromS0 function

[Applies to KMDF and UMDF]

A driver's EvtDeviceArmWakeFromS0 event callback function arms (that is, enables) a device so that it can trigger a wake signal while in a low-power device state, if the system remains in the system working state (S0).

Syntax

EVT_WDF_DEVICE_ARM_WAKE_FROM_S0 EvtDeviceArmWakeFromS0;

NTSTATUS EvtDeviceArmWakeFromS0(
  _In_  WDFDEVICE Device
)
{ ... }

Parameters

Device [in]

A handle to a framework device object.

Return value

If the operation is successful, the EvtDeviceArmWakeFromS0 callback function must return STATUS_SUCCESS or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise it must return a status value for which NT_SUCCESS(status) equals FALSE.

If NT_SUCCESS(status) equals FALSE, the framework calls the driver's EvtDeviceDisarmWakeFromS0 callback function. (The framework does not report a device failure to the PnP manager.)

Remarks

To register an EvtDeviceArmWakeFromS0 callback function, a driver must call WdfDeviceInitSetPowerPolicyEventCallbacks. Additionally, the driver must set IdleCanWakeFromS0 in the IdleCaps member of its WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure.

The EvtDeviceArmWakeFromS0 callback function handles device-specific operations that are needed to enable the device to detect an external event that triggers a wake signal on the bus. The bus driver's EvtDeviceEnableWakeAtBus callback function handles bus-specific operations, such as enabling the PCI bus's Power Management Event (PME) signal.

If the driver has registered an EvtDeviceArmWakeFromS0 callback function, the framework calls it while the device is still in the D0 device power state, before the bus driver lowers the device's power state but after the framework has sent a wait/wake IRP on behalf of the driver.

The process occurs in the following sequence:

1. The framework determines that the device has been idle for a preset amount of time.

2. The framework calls the driver's EvtDeviceArmWakeFromS0 callback function.

3. The framework requests the driver for the device's bus to lower the device's power.

Immediately before your device enters a low power state, the framework will call your driver's EvtDeviceD0Exit callback function.

For more information about when the framework calls this callback function, see PnP and Power Management Scenarios.

You do not need to provide an EvtDeviceArmWakeFromS0 callback function if your device:

• Is a USB device that supports "selective suspend."

• Cannot be powered down while the system remains fully powered.

• Does not require special hardware operations that enable the device to trigger a wake signal.

If your device supports USB "selective suspend" and if your driver sets IdleUsbSelectiveSuspend in the IdleCaps member of its WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure, the framework sends a "selective suspend" request to the USB bus driver when the device has been idle for a preset amount of time.

For more information about this callback function, see Supporting Idle Power-Down.

Examples

To define an EvtDeviceArmWakeFromS0 callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtDeviceArmWakeFromS0 callback function that is named MyDeviceArmWakeFromS0, use the EVT_WDF_DEVICE_ARM_WAKE_FROM_S0 type as shown in this code example:

EVT_WDF_DEVICE_ARM_WAKE_FROM_S0 MyDeviceArmWakeFromS0;

Then, implement your callback function as follows:

_Use_decl_annotations_
NTSTATUS
 MyDeviceArmWakeFromS0 (
    WDFDEVICE  Device
    )
  {...}

The EVT_WDF_DEVICE_ARM_WAKE_FROM_S0 function type is defined in the Wdfdevice.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_DEVICE_ARM_WAKE_FROM_S0 function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

See also

EvtDeviceArmWakeFromSx

EvtDeviceDisarmWakeFromS0

Send comments about this topic to Microsoft