Make Platform-Specific Modifications to Power Manager (Compact 2013)
3/26/2014
The Power Manager sample platform dependent driver (PDD) source file Platform.cpp contains a set of functions that you can modify to customize how Power Manager interacts with your platform. The most important function in this source file is PlatformSetSystemPowerState. PlatformSetSystemPowerState implements the functionality for Power Manager's low-level interactions with the platform hardware and the OS.
There are several modifications that you can make to this function to handle common platform-specific customizations, including:
- Handle critical suspend and shutdown situations
- Modify system behavior before system restart
- Decrease the amount of time it takes for the system to resume
These are just a few examples of platform-specific modifications and optimizations that you can make, as described below. The source code in Platform.cpp has comments that describe many other platform-specific adjustments that you may find useful when customizing and implementing system power states for your platform.
The PlatformSetSystemPowerState function includes a placeholder code section where you can add functionality to cause your system to quickly transition to a suspended or powered-off state. For example, if your system has low battery power, you may want your system to perform several critical hardware-specific actions and then make a kernel I/O control (IOCTL) call that immediately places the OS into the desired state. Because the particulars of these actions are platform-specific, the Power Manager sample PDD implementation does not provide this functionality.
You can add this functionality to PlatformSetSystemPowerState by making code changes to Platform.cpp. The following code path in PlatformSetSystemPowerState sets the fForce variable to TRUE when Power Manager receives a POWER_STATE_CRITICAL, POWER_STATE_OFF or POWER_STATE_RESET power state hint. However, in the Power Manager sample PDD implementation, Power Manager ignores the value of fForce.
if (dwNewStateFlags & (POWER_STATE_CRITICAL | POWER_STATE_OFF | POWER_STATE_RESET))
{
fForce = TRUE;
}
You can modify this code path to implement critical suspend or shutdown functionality that is unique to your platform. For example, you can implement a function called CriticalSuspend that directly calls the XXX_PowerDown functions of all device drivers on your platform before placing the OS in a suspended state. To integrate this function with Power Manager, modify the code path above to call your CriticalSuspend function when Power Manager receives a POWER_STATE_CRITICAL hint flag:
if (dwNewStateFlags & POWER_STATE_CRITICAL)
{
CriticalSuspend ();
}
When you make this code modification, Power Manager calls your CriticalSuspend function after an application calls SetSystemPowerState with the POWER_STATE_CRITICAL hint flag.
The PlatformSetSystemPowerState function has code paths that make direct kernel calls to reset and power off the system. For example, the following code path restarts the system-it does not return from the call to KernelLibIoControl:
if ((dwNewStateFlags & POWER_STATE_RESET) != 0)
{
// Should not return from this call
KernelLibIoControl ((HANDLE) KMOD_OAL, IOCTL_HAL_REBOOT, NULL, 0, NULL, 0, NULL);
Depending on the requirements of your platform, you may want to modify this code path to perform additional steps before the system restarts.
When the system goes into a suspended state, PlatformSetSystemPowerState calls the ForcePageout function to discard code pages from device drivers. This call to ForcePageout is intended for use as a diagnostic tool to debug paging-related problems. You can speed up resume times on production versions of your platform by disabling this code path:
// if (gfPageOutAllModules)
// {
// ForcePageOut ();
// }