EvtDeviceD0Entry function

[Applies to KMDF and UMDF]

A driver's EvtDeviceD0Entry event callback function performs operations that are needed when the driver's device enters the D0 power state.

Syntax

EVT_WDF_DEVICE_D0_ENTRY EvtDeviceD0Entry;

NTSTATUS EvtDeviceD0Entry(
  _In_  WDFDEVICE Device,
  _In_  WDF_POWER_DEVICE_STATE PreviousState
)
{ ... }

Parameters

Device [in]

A handle to a framework device object.

PreviousState [in]

A WDF_POWER_DEVICE_STATE-typed enumerator that identifies the previous device power state.

Return value

If the EvtDeviceD0Entry callback function encounters no errors, it 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.

For more information about this callback function's return values, see Reporting Device Failures.

The framework does not call the driver's EvtDeviceD0Exit callback function after the EvtDeviceD0Entry callback function returns a status value for which NT_SUCCESS(status) equals FALSE.

Remarks

To register an EvtDeviceD0Entry callback function for a device, a driver must call WdfDeviceInitSetPnpPowerEventCallbacks.

If the driver has registered an EvtDeviceD0Entry callback function for a device, the framework calls the function each time the device enters its working (D0) state. A device will enter the D0 state when one of the following occurs:

• A device is enumerated (because the device was plugged in or the system was rebooted).

• The system and all of its devices return to their working states from a low-power state.

• The device returns to its working state after it entered a low-power state because it was idle (if the device supports low-power idle).

• The Plug and Play manager has redistributed the system's hardware resources among the system's devices.

The framework calls the EvtDeviceD0Entry callback function immediately after the device enters its working (D0) state and is available to the driver, but before the device's interrupts have been enabled. The PreviousState parameter identifies the device power state that the device was in before it entered the D0 state.

The callback function must perform any operations that are needed to make the device fully operational, such as loading firmware or enabling device capabilities that are disabled when the device is in a low-power state.

If the EvtDeviceD0Entry callback function returns a status value for which NT_SUCCESS(status) equals FALSE, the framework does the following:

• If the device is starting for the first time, the framework begins an orderly removal sequence for the device.

• If the device is returning from a low-power state to its working state, the framework begins a surprise removal sequence for the device.

The framework does not call the driver's EvtDeviceD0Exit callback function in either of these situations.

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

For more information about drivers that provide this callback function, see Supporting PnP and Power Management in Function Drivers.

The EvtDeviceD0Entry callback function is called at IRQL = PASSIVE_LEVEL. You should not make this callback function pageable.

Examples

To define an EvtDeviceD0Entry 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 EvtDeviceD0Entry callback function that is named MyDeviceD0Entry, use the EVT_WDF_DEVICE_D0_ENTRY type as shown in this code example:

EVT_WDF_DEVICE_D0_ENTRY  MyDeviceD0Entry;

Then, implement your callback function as follows:

_Use_decl_annotations_
NTSTATUS
 MyDeviceD0Entry(
    WDFDEVICE  Device,
    WDF_POWER_DEVICE_STATE  PreviousState
    )
  {...}

The EVT_WDF_DEVICE_D0_ENTRY 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_D0_ENTRY 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

EvtDeviceD0Exit

Send comments about this topic to Microsoft