Power Management Application Interface (Compact 7)
3/12/2014
Power Manager provides several functions to allow applications to affect system and device power management. Of the functions in this list, only GetSystemPowerState, SetPowerRequirement, and ReleasePowerRequirement are intended for use by typical applications. The remaining functions, SetSystemPowerState, GetDevicePower, and SetDevicePower, are intended for use by OEM applications such as Control Panel utilities. For example, because SetDevicePower does not implement a reference counting mechanism, it cannot be called by multiple applications.
The following table lists the power management functions of the application interface.
Application Interface Functions
| Function | Description |
|---|---|
SetPowerRequirement |
Requests that Power Manager maintain the power state of a device at a minimum level. |
ReleasePowerRequirement |
Informs Power Manager that it no longer needs to maintain the device minimum power state set in a previous call to SetPowerRequirement. |
GetSystemPowerState |
Returns the name of the current system power state. |
SetSystemPowerState |
Requests that Power Manager change the current system power state. |
GetDevicePower |
Returns the current power state of a device. |
SetDevicePower |
Requests that Power Manager change the power state of a device. |
Applications call SetPowerRequirement and ReleasePowerRequirement to request device power levels. In some situations, applications may want to influence how Power Manager administers system power states. For example:
- A pager application might want to keep device COM3: at device power state D3 or higher while the rest of the system is in a suspended state so that an incoming page can wake the system
- A streaming audio application might want to keep the network card and audio system at full power even when the system is on battery power and has been idle for a while.
To handle these situations, Power Manager provides the SetPowerRequirement function to support applications that have special power management needs. Applications can call SetPowerRequirement to request that Power Manager set a minimum power requirement on device power states. If an application sets a power requirement, Power Manager does not allow devices to set their own power state below that specified by the requirement. When Power Manager transitions the platform to a new system power state, it typically keeps this device requirement in force, even if doing so maintains the device at a higher power level than specified for the new system power state.
Power Manager normally ignores device power requirements when the OS is in a suspended state. When the OS is in a suspended state, the CPU is stopped and the OS does not service interrupts. A device driver must disable itself if the OS is suspended. Power Manager can ignore device power requirements under other circumstances, as well. For example, you may choose to interpret the POWER_STATE_CRITICAL flag as indicating that the battery level of the OS is critically low and that all devices should be turned off. Modifying the interpretation of power state flags (also referred to as hints, as explained below) is described in Implement System Power States.
Applications call GetSystemPowerState and SetSystemPowerState to influence system power state transitions. Although you may want the application to directly change the system power state by calling SetSystemPowerState, applications cannot know which power states are available on a given Windows Embedded Compact-based platform, nor can they know the characteristics of the system power states that are available. Rather than call the SetSystemPowerState function with an explicit state name, you can design your application to invoke SetSystemPowerState with a power state bit mask describing the characteristics of the power state into which the system should transition. Each power state bit is referred to as a hint because it doesn't necessarily map directly to a system power state. Some hints can map to multiple system power states. For example, an application might request a system power state change by setting the POWER_STATE_SUSPEND hint flag. On a platform that supports Suspended and SuspendedCradle system power states, Power Manager could use this hint to transition into either state, depending on whether the device is in a cradle at the time of the request. If the device is removed from the cradle while in the SuspendCradle state, Power Manager transitions into the Suspended state.
The following table lists predefined power state hints and their suggested interpretations.
Power State Hints
| Hint | Description |
|---|---|
POWER_STATE_ON |
The highest functional level and highest power consumption mode of the platform. Devices are powered on and the platform is operating at a normal performance level. |
POWER_STATE_OFF |
All devices are powered off. Resuming from this state results in a cold boot. |
POWER_STATE_CRITICAL |
The battery is critically low. The OS carries out required system maintenance, turns off power to devices, and puts dynamic random-access memory (DRAM) into a self-refresh state. Resuming from this state results in a cold boot. |
POWER_STATE_BOOT |
The system is in the process of booting. |
POWER_STATE_IDLE |
No devices are in use, and there is no user interaction. Devices enter a low-power state and the platform enters a low-power mode. You can use this state as an alternative to suspending the system if the power saved from the low-power mode is satisfactory. |
POWER_STATE_RESET |
Flushes files, shuts down devices, and issues the IOCTL_HAL_REBOOT command to the kernel. |
POWER_STATE_SUSPEND |
The OS is suspended and Power Manager ultimately calls a PowerOff function. |
These power state hints are defined in Pm.h. The Power Manager sample PDD implementation does not use all of the power state hints listed in this table. You can define new power state hints that are specific to your platform, and you can modify Power Manager so that it interprets power state hints differently for the system power states defined for your platform. For more about modifying Power Manager system power state functionality, see Implement System Power States.
When an application requests a new power state by calling SetSystemPowerState with one or more power state hints, Power Manager does the following:
- Broadcasts a PBT_TRANSITION notification on the notification message queue.
- Updates the device power state, if necessary, for all device drivers. If a device is already at an acceptable power state for the new system power state, Power Manager will not issue an IOCTL_POWER_SET command to the device driver for that device.
- If the system is resuming from a suspended state, Power Manager broadcasts a PBT_RESUME notification on the notification message queue.
For more about Power Manager application interface functions and power state hints, see Windows Embedded Compact 7 documentation.