Muokkaa

Jaa

Power Policy Ownership in UMDF

  • Artikkeli

Warning

UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2.

The archived UMDF 1 samples can be found in the Windows 11, version 22H2 - May 2022 Driver Samples Update.

For more info, see Getting Started with UMDF.

For each device, one (and only one) of the device's drivers must be the device's power policy owner. The power policy owner determines the appropriate device power state for a device and sends requests to the device's driver stack whenever the device's power state should change.

Framework-based drivers do not contain code that requests changes in a device's power state, because the framework provides that code. By default, whenever the system enters a system sleeping state, the framework asks the driver for your device's bus to lower the device power state to D3. (Your driver can change the default behavior so that the framework sets your device's sleep state to D1 or D2, if the device provides wake-up capabilities.) When the system power returns to its working (S0) state, the framework requests the bus driver to restore your device to its working (D0) state.

The power policy owner is also responsible for enabling and disabling the following device features:

  • Your device's ability to enter a low-power (sleeping) state when it is idle and the system remains in its working (S0) state

  • Your device's ability to wake itself from a sleeping state when it detects an external event

  • Your device's ability to wake up the entire system from a system sleeping state when it detects an external event

If your device supports these idle power-down and system wake-up capabilities, the power policy owner can also support the framework's IPowerPolicyCallbackWakeFromS0 and IPowerPolicyCallbackWakeFromSx interfaces, which define a set of power policy event callback functions.

By default, UMDF-based drivers are not power policy owners. The device's kernel-mode function driver is the default power policy owner. (If there is no kernel-mode function driver and the bus driver has called WdfPdoInitAssignRawDevice, the bus driver is the power policy owner). If you want your UMDF-based driver to be the power policy owner for a driver stack, the driver must call IWDFDeviceInitialize::SetPowerPolicyOwnership, and the kernel-mode default power policy owner must call WdfDeviceInitSetPowerPolicyOwnership to disable ownership.

In addition, if you are providing a UMDF-based driver for a USB device, and if you want your driver to be the power policy owner, the driver's INF file must contain an INF AddReg directive that sets the WinUsbPowerPolicyOwnershipDisabled value in the registry. If this REG_DWORD-sized value is set to any nonzero number, it disables the WinUSB driver's ability to be the device's power policy owner. The AddReg directive must be in an INF DDInstall.HW section, as the following example shows.

[MyDriver_Install.NT.hw]
AddReg=MyDriver_AddReg

[MyDriver_AddReg]
HKR,,"WinUsbPowerPolicyOwnershipDisabled",0x00010001,1

The framework does the following work for the power policy owner:

  • It handles all power policy communication between your driver and the rest of the driver stack. For example, your driver does not have to request the bus driver to change the device's power state, because the framework makes the request.

  • If your driver registers power policy event callback functions, the framework calls them when it is time to enable or disable the device's ability to wake itself from a low-power state.

  • If your driver allows users to modify idle and wake settings, the framework provides a user interface in the form of a property sheet page that Device Manager displays.

For more information about the power policy owner's responsibilities, see the following topics: