EvtDeviceReleaseHardware function

[Applies to KMDF and UMDF]

A driver's EvtDeviceReleaseHardware event callback function performs operations that are needed when a device is no longer accessible.

Syntax

EVT_WDF_DEVICE_RELEASE_HARDWARE EvtDeviceReleaseHardware;

NTSTATUS EvtDeviceReleaseHardware(
  _In_  WDFDEVICE Device,
  _In_  WDFCMRESLIST ResourcesTranslated
)
{ ... }

Parameters

Device [in]

A handle to a framework device object.

ResourcesTranslated [in]

A handle to a resource list object that identifies the translated hardware resources that the Plug and Play manager has assigned to the device.

Return value

If the EvtDeviceReleaseHardware 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. Do not return STATUS_NOT_SUPPORTED.

Remarks

To register an EvtDeviceReleaseHardware callback function, your driver must call WdfDeviceInitSetPnpPowerEventCallbacks.

If a driver has registered an EvtDeviceReleaseHardware callback function, the framework calls it during the following transitions:

• Resource rebalancing
• Orderly removal
• Surprise removal

The framework calls the EvtDeviceReleaseHardware callback function after the framework has stopped sending I/O requests to the device, any interrupts assigned to the device have been disabled and disconnected, and the device has been turned off.

When the framework calls the EvtDeviceReleaseHardware, the PDO for the device still exists and can be queried for device information that is available in the powered off state, for example PCI configuration state.

In addition, the translated hardware resources that the framework supplies to EvtDeviceReleaseHardware are still assigned to the device. The primary purpose of this callback function is to release those resources, and in particular to unmap any memory resources that the driver's EvtDevicePrepareHardware callback function mapped. The driver can also use this callback to perform any other driver or device management activity that might be required in the powered down state. Usually, all other hardware shutdown operations should take place in the driver's EvtDeviceD0Exit callback function.

The framework always calls the driver's EvtDeviceReleaseHardware callback function if the driver's EvtDevicePrepareHardware callback function has been called, even if EvtDevicePrepareHardware returned a failure code.

A driver for a device that has child devices can control the order in which the framework calls the EvtDeviceReleaseHardware callback functions for the parent device and its children by calling WdfDeviceInitSetReleaseHardwareOrderOnFailure from within its EvtDriverDeviceAdd callback function.

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

For more information about hardware resources, see Hardware Resources for Framework-Based Drivers.

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

Examples

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

EVT_WDF_DEVICE_RELEASE_HARDWARE  MyDeviceReleaseHardware;

Then, implement your callback function as follows:

_Use_decl_annotations_
NTSTATUS
 MyDeviceReleaseHardware (
    WDFDEVICE  Device,
    WDFCMRESLIST  ResourcesTranslated
    )
  {...}

The EVT_WDF_DEVICE_RELEASE_HARDWARE 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_RELEASE_HARDWARE 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

EvtDevicePrepareHardware

Send comments about this topic to Microsoft