WdfDeviceInitSetReleaseHardwareOrderOnFailure function (wdfdevice.h)

Article
02/22/2024

[Applies to KMDF and UMDF]

The WdfDeviceInitSetReleaseHardwareOrderOnFailure method specifies whether the framework calls the driver's EvtDeviceReleaseHardware callback function immediately after device failure, or waits until all child devices have been removed.

Syntax

void WdfDeviceInitSetReleaseHardwareOrderOnFailure(
  [in] PWDFDEVICE_INIT                       DeviceInit,
  [in] WDF_RELEASE_HARDWARE_ORDER_ON_FAILURE ReleaseHardwareOrderOnFailure
);

Parameters

[in] DeviceInit

A pointer to a WDFDEVICE_INIT structure.

[in] ReleaseHardwareOrderOnFailure

A WDF_RELEASE_HARDWARE_ORDER_ON_FAILURE-typed enumerator that specifies when the framework calls the driver's EvtDeviceReleaseHardware callback function.

Return value

None

Remarks

Typically, the framework calls a driver's EvtDeviceReleaseHardware callback function after it has called the EvtDeviceReleaseHardware function for all child devices that the driver enumerates.

In the event of a device power-up or power-down failure, however, the framework might call the driver's EvtDeviceReleaseHardware before it has called the EvtDeviceReleaseHardware functions for all child devices.

To override this default behavior, a driver can call WdfDeviceInitSetReleaseHardwareOrderOnFailure to specify that, even in device failure scenarios, the framework should always wait to call its EvtDeviceReleaseHardware function until it has called the EvtDeviceReleaseHardware functions of the child devices.

For example, a bus driver that performs hardware access on behalf of its child devices could use this technique to ensure that its child devices do not request access to hardware after the framework has called the bus driver's EvtDeviceReleaseHardware callback function.

If a driver calls WdfDeviceInitSetReleaseHardwareOrderOnFailure, it must do so before it calls WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.

Examples

The following code example shows how a bus driver can request that the framework wait to call its EvtDeviceReleaseHardware callback function until all of its child devices have been removed.

WdfDeviceInitSetReleaseHardwareOrderOnFailure(
                       DeviceInit,
                       WdfReleaseHardwareOrderOnFailureAfterDescendants
                       );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.11
Minimum UMDF version	2.0
Header	wdfdevice.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf)