WdfDeviceWdmAssignPowerFrameworkSettings function (wdfdevice.h)

Artikel
04/18/2022

[Applies to KMDF and UMDF]

The WdfDeviceWdmAssignPowerFrameworkSettings method registers power management framework (PoFx) settings for single-component devices.

Syntax

NTSTATUS WdfDeviceWdmAssignPowerFrameworkSettings(
  [in] WDFDEVICE                     Device,
  [in] PWDF_POWER_FRAMEWORK_SETTINGS PowerFrameworkSettings
);

Parameters

[in] Device

A handle to the framework device object for which PoFx settings are being specified.

[in] PowerFrameworkSettings

A pointer to a WDF_POWER_FRAMEWORK_SETTINGS structure that describes the client driver’s PoFx settings.

Return value

The WdfDeviceWdmAssignPowerFrameworkSettings method returns an NTSTATUS value that indicates success or failure of the operation.

Return code	Description
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS structure is incorrect.
STATUS_INVALID_DEVICE_REQUEST	The calling driver is not the device's power policy owner.
STATUS_INVALID_PARAMETER	An invalid Settings value is detected.

This method also might return other NTSTATUS values.

Remarks

The WdfDeviceWdmAssignPowerFrameworkSettings method applies only to single-component devices.

Before calling this method, the client driver must first successfully call WdfDeviceAssignS0IdleSettings and set the IdleTimeoutType field of the WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS structure to SystemManagedIdleTimeout or SystemManagedIdleTimeoutWithHint.

A driver must call WdfDeviceWdmAssignPowerFrameworkSettings before or during the first time a device starts. Because a device can start more than once, for example if resource rebalancing occurs, a driver might call this method from within EvtDriverDeviceAdd or EvtDeviceSelfManagedIoInit. The framework calls these functions only once, even if the device is started more than once.

Alternatively, the driver could keep track of whether it has already called WdfDeviceWdmAssignPowerFrameworkSettings, and call it from one of the following callback functions: EvtDevicePrepareHardware, EvtDeviceD0Entry, EvtDeviceD0EntryPostInterruptsEnabled, or EvtDeviceSelfManagedIoRestart.

If your driver calls WdfDeviceWdmAssignPowerFrameworkSettings more than once, the framework generates a verifier error.

The power management framework (PoFx) is available only on Windows 8 and later. When running on an operating system that does not support PoFx, WdfDeviceWdmAssignPowerFrameworkSettings takes no action and returns STATUS_SUCCESS.

For more information, see Supporting Functional Power States and Overview of the Power Management Framework.

Examples

In the following code example, the driver initializes a WDF_POWER_FRAMEWORK_SETTINGS structure by calling the WDF_POWER_FRAMEWORK_SETTINGS_INIT function. The driver then manually sets some of the members of the structure, and then calls WdfDeviceWdmAssignPowerFrameworkSettings.

NTSTATUS status;
WDF_POWER_FRAMEWORK_SETTINGS poFxSettings;

WDF_POWER_FRAMEWORK_SETTINGS_INIT(&poFxSettings);

poFxSettings.EvtDeviceWdmPostPoFxRegisterDevice = 
                        SingleCompWdmEvtDeviceWdmPostPoFxRegisterDevice;
poFxSettings.EvtDeviceWdmPrePoFxUnregisterDevice =
                        SingleCompWdmEvtDeviceWdmPrePoFxUnregisterDevice;

poFxSettings.Component = &component;
poFxSettings.ComponentIdleStateCallback = 
                        SingleCompWdmIdleStateCallback;
poFxSettings.PoFxDeviceContext = (PVOID) Device;
    
status = WdfDeviceWdmAssignPowerFrameworkSettings(Device, &poFxSettings);

Requirements

Requirement	Value
Minimum supported client	Windows 8
Target Platform	Universal
Minimum KMDF version	1.11
Minimum UMDF version	2.33
Header	wdfdevice.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf)

Delen via