Application Power Management for Mobility

Transcription

1 Application Power Management for Mobility White Paper March 20, 2002 Copyright 2002 Intel Corporation

2 Contents 1. Introduction Overview Audience Application Power Management for Mobility Extending battery life Handling system sleep/wake power transitions Preventing the system from transitioning to sleep mode Implementing Application Power Management for Mobility Implementation steps for extending battery life Implementation steps for handling system sleep/wake power transitions Implementation steps for preventing the system from transitioning to sleep mode Proof-of-concept application Microsoft Windows Power Management APIs and Messages Power status GetSystemPowerStatus WM_POWEBOADCAST Power schemes EnumPwrSchemes GetActivePwrScheme System Power Scheme change Execution State SetThreadExecutionState Intel Mobility Application Power Demo Overview Implementation of Application Power Management for Mobility Extending battery life Handling system sleep/wake power transitions Installation Source Code Conclusion Appendix A: Intel Mobility Application Power Demo Executable and Source Code

3 Acronyms API DLL MFC MSDN UI Application Programming Interface Dynamic Link Library Microsoft * Foundation Classes Microsoft* Developer Network User Interface * Other names and brands may be claimed as the property of others 3

4 1. Introduction 1.1. Overview A good user experience and longer battery life are critical factors for the future growth of mobile systems. Application software has a key role to play in improving user experience as well as in extending battery life. This white paper discusses the concept of Application Power Management for Mobility. Application Power Management for Mobility describes how application software can improve user experience and extend battery life. This white paper includes, steps for implementing Application Power Management for Mobility within an application, references to available Microsoft* Windows Power Management Application Programming Interfaces (APIs), and an overview of the proof-of-concept application developed by Intel software labs Audience The intended audience for this white paper is architects, designers and developers writing applications for Microsoft* Windows* operating systems including: Windows* 98, Windows* 98SE, Windows* ME, Windows* 2K and Windows* XP. This paper also provides a good overview of Application Power Management for Mobility for managers, validation engineers, technical-marketing engineers or anyone defining/designing an application. Other names and brands may be claimed as the property of others 4

5 2. Application Power Management for Mobility Application Power Management for Mobility identifies three distinct power management capabilities for applications to implement. These power management capabilities are: extending battery life when the system is battery powered, handling system sleep/wake power transitions, and preventing the system from transitioning to sleep mode when the application is in use Extending battery life When the system is battery powered, applications can extend battery life by reducing the performance/quality of features, turning off background activities, or both. Implementing these operations in an application increases the processor idle 1 time. Since processor power consumption when idle is significantly lower than when active 2, this results in longer battery life. There is no pre-defined list of performance/quality features and background activities for extending battery life. The performance/quality features and background activities are specific to an application. Some examples could include: educing the quality of video and audio playback in a DVD application to extend playtime while traveling. Turning off automatic spell check and grammar correction within a word processing application to finish the document when the battery is low. educing the frequency of stock quote updates in web based financial applications to remain online longer. When a system is battery powered applications can extend battery life. In addition, applications can define other criteria to determine when to extend battery life. These other criteria can be based on current battery power status, current system power scheme 3, or both. For example, an application can extend battery life when one or more conditions below are met: The percentage of remaining battery power is below a specific threshold. The remaining battery time is below a certain amount of time. The system is using a particular power scheme. An application s User Interface (UI) can provide options for specifying both how and when, to reduce performance/quality of features, to turn off background activities or both. User input is important, since users know their requirements and their environment best. User experience may not be optimal if applications predefined these settings without any options in the UI. 1 Idle refers to the processor state when the processor isn t executing any instructions 2 Active refers to the processor state when the processor is executing instructions 3 Windows* operating systems allow users to set power settings most appropriate for their systems using power schemes. For more information on power schemes refer to the Windows* documentation. 5

6 2.2. Handling system sleep/wake power transitions In Windows* operating systems, the sleep power transition refers to switching off the system to a Stand By or a Hibernate mode, and the wake power transition refers to switching on the system from a Stand By or a Hibernate mode. The Stand by and Hibernate modes allow users to switch off and switch on systems a lot quicker than the regular shut down and boot processes. Applications can improve user experience by handling system sleep/wake power transitions. Handling system sleep/wake power transitions means, applications should survive these power transitions without, requiring a restart, loss of data, and change in state. In addition, for a good user experience, applications should handle the power transitions transparently with no user interaction. There is no generalized list of tasks for handling system sleep/wake power transitions. The tasks depend on the application and will vary between applications. Some tasks for applications to consider include: Saving state/data prior to the sleep transition and restoring state/data after the wake transition. Closing all open system resource handles such as files and I/O devices prior to the sleep transition. Disconnecting all communication links prior to the sleep transition and re-establishing all communication links after the wake transition. Synchronizing all remote activity (like writing back to remote files or to remote databases) after the wake transition. Stopping any ongoing user activity (for example: streaming video, or file download) prior to the sleep transition and resuming the user activity after the wake transition Preventing the system from transitioning to sleep mode In Windows* operating systems, the system s transition to sleep mode refers to switching off the system to a Stand By or a Hibernate mode. To conserve battery power, Windows* operating systems switch off the system to a Stand By or a Hibernate mode when they don t detect certain activities for a specific period 1 of time. The activities that Windows* operating systems don t automatically detect are: disk activity, CPU activity and video display activity. The activities that Windows* operating systems automatically detect are: keyboard input, mouse input, server activity, and changing window focus. Applications like video players and presentation managers display video for long periods of time without any user input and this often results in Windows* operating system switching off the system display during a video play back or a presentation. To deal with this situation, the options available for users are either to switch on the system display each time it switches off, or to delay the system transition to sleep mode by increasing the waiting period for display activity. Neither of these operations is optimal since switching on the system display each time reduces the user experience, and delaying the system transition to sleep mode wastes battery power when the system is not in use for extended periods. When an application is performing an activity that the operating system doesn t detect, it can prevent the system from transitioning to sleep mode by informing the operating system. This results in a better user experience as well as in better power management. 1 Windows* operating systems allow users to specify the time period using power schemes. For more information on power schemes refer to the Windows* documentation. 6

7 2.4. Implementing Application Power Management for Mobility This section outlines the steps for implementing Application Power Management for Mobility within an application Implementation steps for extending battery life The implementation steps for an application to extend battery life include: 1. Identify the application features where users may be willing to reduce performance/quality for extended battery life. 2. Identify the application background activities which users may be willing to turn off for extended battery life. 3. When a system is battery powered the application can extend battery life. In addition, the application can define other criteria to determine when to extend battery life. These other criteria can be based on current battery power status, current system power scheme, or both. 4. eview the Microsoft* Windows* Power Management APIs and Messages section in this white paper. This section outlines available Windows* operating system APIs and messages for retrieving system power information like system power source, battery status, and system power schemes. 5. Design and implement a UI so users can specify both how and when to reduce performance/quality of features, and/or to turn off background activities. 6. Implement application logic to retrieve system power information and determine when to reduce performance/quality of features, and/or to turn off background activities. 7. Implement application logic to reduce performance/quality of features, and/or to turn off background activities Implementation steps for handling system sleep/wake power transitions Windows* operating systems send messages to applications notifying them of system sleep and wake power transitions. Applications should respond to these messages and perform necessary operations to handle the power transitions. The implementation steps for an application to handle system sleep/wake power transitions include: 1. Investigate the application behavior during system sleep/wake power transitions. In Windows operating systems, the sleep power transition refers to switching off the system to a Stand By or a Hibernate mode, and the wake power transition refers to switching on the system from a Stand By or a Hibernate mode. 2. Identify the issues causing the application to, require a restart, lose data, or change state. 3. eview the Microsoft* Windows* Power Management APIs and Messages section in this white paper. This section outlines available Windows* operating system APIs and messages for responding to system sleep/wake power transitions. In Windows* Power Management APIs terminology, the system sleep and wake power transition notifications are referred to as suspend and resume messages. 4. Implement application logic to respond to the power transition notifications and perform the necessary operations to survive the power transitions without, requiring a restart, loss of data and change in state. For a good user experience, handle the power transitions with no user interaction. 7

8 Implementation steps for preventing the system from transitioning to sleep mode The implementation steps for an application to prevent the system from transitioning to sleep mode include: 1. Identify application activities that the operating system doesn t detect. 2. eview the Microsoft* Windows* Power Management APIs and Messages section in this white paper. This section outlines available Windows* operating system APIs for preventing the system from transitioning to sleep mode. 3. Implement application logic to prevent the system from transitioning to sleep mode when the application is performing activities that the operating system doesn t detect Proof-of-concept application Intel software labs developed the Intel Mobility Application Power Demo as a proof-of-concept application to illustrate Application Power Management for Mobility. This proof-of-concept application simulates support for extending battery life and handling system sleep/wake power transitions. Intel Mobility Application Power Demo and its source code may be used as a reference for implementing Application Power Management for Mobility within your application. efer to the Intel Mobility Application Power Demo section for more details. 8

9 3. Microsoft Windows Power Management APIs and Messages The details covered in this section are applicable to Microsoft* Windows* operating systems including: Windows* 98, Windows* 98SE, Windows* ME, Windows* 2K and Windows* XP. This section covers only the Microsoft* Windows* Power Management APIs and messages required for implementing Application Power Management for Mobility. For a complete reference to all Microsoft* Windows* Power Management APIs and messages refer to the Microsoft* Developer Network (MSDN) library. Note: Most of the content is this section was taken from the MSDN library Power status This section covers the GetSystemPowerStatus API and the WM_POWEBOADCAST message. The GetSystemPowerStatus API is used to retrieve system power information such as system power source and current battery power status. The WM_POWEBOADCAST message is sent to notify applications of system sleep/wake power transitions and changes in system power status GetSystemPowerStatus The GetSystemPowerStatus API is used to retrieve system power information. This status indicates whether the system is running on AC or DC (battery) power, whether the battery is currently charging, and how much battery life remains. To use this API, include the Windows.h header file and link with the Kernel32.lib library. BOOL GetSystemPowerStatus(LPSYSTEM_POWE_STATUS psystempowerstatus); Parameter: LPSYSTEM_POWE_STATUS psystempowerstatus An out pointer to SYSTEM_POWE_STATUS structure that receives status information. eturn Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call the GetLastError API (efer to MSDN for GetLastError details). Structure SYSTEM_POWE_STATUS typedef struct _SYSTEM_POWE_STATUS { BYTE ACLineStatus; BYTE BatteryFlag; BYTE BatteryLifePercent; BYTE eserved1; DWOD BatteryLifeTime; DWOD BatteryFullLifeTime; } SYSTEM_POWE_STATUS, *LPSYSTEM_POWE_STATUS; The structure members are: ACLineStatus Indicates AC power status. 0 for Offline (Battery/DC), 1 for Online (AC) and 255 for Unknown status. 9

10 BatteryFlag Indicates Battery charge status. 1 for High, 2 for Low, 4 for Critical, 8 for Charging, 128 for No system battery, and 255 for Unknown status. BatteryLifePercent Percentage of battery charge remaining. The value can range from 0 to 100 and is set to 255 if the value is unknown. eserved1 eserved, must be zero. BatteryLifeTime Number of seconds of battery life remaining, or 1 if unknown. BatteryFullLifeTime Number of seconds of battery life when at full charge, or 1 if unknown WM_POWEBOADCAST The WM_POWEBOADCAST message notifies applications of system sleep/wake power transitions and changes in system power status. An application window receives this message through its WindowProc function. To adhere to the API documentation and Windows* operating system terminology, in this section the term suspend refers to system sleep power transition and the term resume refers to system wake transition. Note: Windows* operating systems do not send any notification to applications when a critical suspension occurs (for example, a battery failure). A critical resume notification (refer below to PBT_APMESUMECITICAL) is sent to applications after the system resumes from critical suspension. In such a scenario, an application should make a best effort attempt to restore its state and data. To handle the message, include the Windows.h header file. LESULT CALLBACK WindowProc( HWND hwnd, UINT umsg, WPAAM wparam, LPAAM lparam ); // handle to window // message id (WM_POWEBOADCAST) // power-management event // function-specific data Parameters: wparam Specifies the power-management event. PBT_APMBATTEYLOW Battery power is low. Not all BIOS implementations provide low battery notifications so this event may never be broadcast on some systems. PBT_APMOEMEVENT OEM-defined BIOS signal event. The lparam specifies the OEM-defined event code and is in the range 0200h 02FFh. Not all BIOS implementations provide OEM event notifications so this event may never be broadcast on some systems. PBT_APMPOWESTATUSCHANGE Power status has changed (for example, there has been a switch from battery power (DC) to AC). This message is also broadcast when the battery s life drops to less than 5 minutes, when the remaining percentage of battery life drops below 10%, or when the battery life changes by 3%. The application should process this message by calling the GetSystemPowerStatus function to retrieve the current power status of the system. PBT_APMQUEYSUSPEND is a request for permission to suspend the system. Applications granting permission to suspend should prepare for the suspension before returning. lparam a DWOD value specifies action flags. If bit 0 is 1, the application can prompt for directions on how to prepare for the suspension; otherwise, the application must prepare without user intervention. All 10

11 other bits are reserved. Any operation taking longer than 20 seconds should be accomplished here, since the system allows only 20 seconds for operations to complete during PBT_APMSUSPEND. eturn TUE to grant the request for suspend and return BOADCAST_QUEY_DENY to deny the request. PBT_APMQUEYSUSPENDFAILED the suspension request is denied. This event is broadcast when any application or driver returns BOADCAST_QUEY_DENY to a previous PBT_APMQUEYSUSPEND event. Applications should respond by resuming normal operations. PBT_APMESUMEAUTOMATIC is broadcast when the system wakes up automatically to handle an event. Applications should not respond unless they are handling the event without user intervention. Detection of user activity after broadcasting PBT_APMESUMEAUTOMATIC, broadcasts a PBT_APMESUMESUSPEND event to let applications know they can resume full user interaction. PBT_APMESUMECITICAL Operation resuming after critical suspension such as a battery failure. Since a critical suspension occurs without prior notification, resources and data previously available may not be present when the application receives the event. Applications should make a best effort attempt to restore their state. PBT_APMESUMESUSPEND Operation resuming after suspension. Applications can receive this event only if they received the PBT_APMSUSPEND event before the system was suspended. PBT_APMSUSPEND the system is suspending operation and the message is broadcast immediately before the system enters the suspended state. This is broadcast when all applications and drivers have returned TUE to a previous PBT_APMSUSPENDQUEY event. Applications should process this event by completing all tasks necessary to save state and data. Applications have approximately 20 seconds to handle this and are interrupted if operations continue after the 20 seconds have expired. lparam Event-specific data, refer to wparam information for more details. For most events, this parameter is reserved and not used. eturn Value: For PBT_APMQUEYSUSPEND event - return TUE to grant a request and return BOADCAST_QUEY_DENY to deny a request. For other events there is no return value Power schemes The APIs for enumerating all the power schemes installed on the system and retrieving the current system power scheme are EnumPwrSchemes and GetActivePwrScheme. To use these APIs include Powrprof.h header file and link with Powrprof.lib library EnumPwrSchemes The EnumPwrSchemes API enumerates all power schemes installed on a system. For each enumerated power scheme, EnumPwrSchemes calls a callback function with information about the power scheme. This call to the callback function is synchronous and does not return until all schemes are enumerated. BOOL EnumPwrSchemes(PWSCHEMESENUMPOC lpfnpwrschemesenumproc, LPAAM lparam); Parameter: PWSCHEMESENUMPOC lpfnpwrschemesenumproc A pointer to a callback function for each enumerated power scheme. 11

12 LPAAM lparam A user-defined value passed to the callback function. eturn Value: When the function succeeds, the return value is EO_SUCCCESS. When the function fails, the return value is zero. To get extended error information, call GetLastError API. Callback function: typedef BOOLEAN (CALLBACK* PWSCHEMESENUMPOC)( UINT uiindex, // power scheme index DWOD dwname, // size of the sname string, in bytes LPTST sname, // name of the power scheme DWOD dwdesc, // size of the sdesc string, in bytes LPTST sdesc, // description string PPOWE_POLICY pp, // receives the power policy LPAAM lparam // user-defined value ); The name and description strings are null-terminated strings, and pp is a pointer to a POWE_POLICY structure containing the power policy scheme. The POWE_POLICY structure contains power policy settings unique to each scheme. Since power policy settings aren t used in Application Power Management for Mobility, information on the POWE_POLICY structure is omitted from this paper. efer to the MSDN library for details on POWE_POLICY structure GetActivePwrScheme The GetActivePwrScheme API retrieves the active power scheme (current system power scheme) index. BOOL GetActivePwrScheme(PUINT puiid); Parameter: PUINT puiid A pointer to a variable that receives the index of the active power scheme. eturn Value: If the function succeeds, the return value is nonzero, and if the function fails, the return value is zero. To get extended error information, call the GetLastError API System Power Scheme change Windows* operating systems do not notify applications when the system power scheme is changed either programmatically or by the user. To handle a system power scheme change, the Intel Mobility Application Power Demo relies on Windows* Timer messages to retrieve system power scheme information (using the GetActivePwrScheme API) at regular intervals. For details on Windows* Timer messages refer to the MSDN library Execution State This section covers the SetThreadExecutionState API, which is used to prevent the system from transitioning to sleep mode. 12

13 SetThreadExecutionState The SetThreadExecutionState API enables applications to inform the operating system when they are in use and thereby preventing the system from transitioning to sleep mode. To use this API, include the Windows.h header file and link with the Kernel32.lib library. EXECUTION_STATE SetThreadExecutionState(EXECUTION_STATE esflags); Parameter: EXECUTION_STATE esflags Specifies the thread's execution requirements. This parameter can be one or more of the following values: ES_SYSTEM_EQUIED - Informs the system that the thread is performing some operation that is not normally detected as activity by the system. ES_DISPLAY_EQUIED - Informs the system that the thread is performing some operation that is not normally detected as activity by the system. ES_USE_PESENT - Informs the system that a user is present. If a user is present, the system will use the power policy settings set by the user. Otherwise, the system does not wake the display device and will return to the sleeping state as soon as possible. ES_CONTINUOUS - When this flag is used with one or more of the other state flags it informs the system that the state being set should remain in effect indefinitely. To reset or clear the indefinite condition, call SetThreadExecutionState again with just the ES_CONTINUOUS flag. eturn Value: If the function succeeds, the return value is previous thread execution state, and if the function fails, the return value is NULL. For example, a presentation application should call SetThreadExecutionState with ES_SYSTEM_EQUIED, ES_DISPLAY_EQUIED and ES_CONTINUOUS flags prior to a slide show, and when the slide show is complete the presentation application should call SetThreadExecutionState with just the ES_CONTINIOUS flag. 13

14 4. Intel Mobility Application Power Demo Intel software labs developed the Intel Mobility Application Power Demo as a proof-of-concept application to illustrate Application Power Management for Mobility. The Mobility Application Power Demo and its source code may be used as a reference for implementing Application Power Management for Mobility within your application. This section includes, an overview of the Mobility Application Power Demo, a description on how the Mobility Application Power Demo simulates support for Application Power Management for Mobility, and how to access the Mobility Application Power Demo and its source code Overview The Mobility Application Power Demo, like Microsoft s Notepad is a simple word processing application allowing users to open, edit and save text documents. The application simulates support for extending battery life and for handling system sleep/wake power transitions. It does not simulate support for preventing the system from transitioning to sleep mode. Other application features include: Creating new or opening existing documents in plain text format. Copying, cutting and pasting text. Undoing changes made to the document. Saving changes to an existing document. Writing to a new document in plain text format. Printing and print previewing the document. Tracking the most recently opened documents. Viewing battery status and battery details like name, type, and manufacturer s name. Selecting save options like directory to save to and prompting for unsaved data. The application s main UI shown in Figure 1 includes, a menu/tool bar for accessing application features, a status bar indicating application status, and an edit window for writing/editing text documents. The menu items provides access to the following application features: Use the File menu for creating, opening, saving and printing text files. Use the Edit menu for cutting, copying and pasting text. Use the View menu for viewing the battery status information, and to show or hide the status/tool bars. Use the Options menu for selecting the save and the power options. Use the Help menu for viewing the about box and the overview of the Mobility Application Power Demo. 14

15 4.2. Implementation of Application Power Management for Mobility The Mobility Application Power Demo s implementation of the Application Power Management for Mobility concepts is just a simulation. The application s options and UI used to simulate the concepts are for illustration purposes only and should not be considered a design guideline Extending battery life To extend battery life, the Mobility Application Power Demo implements the following: Two modes of operation: Normal mode and Low Power mode. A Power Options UI, so users can specify how and when to extend battery life. Normal mode versus Low Power mode The Mobility Application Power Demo switches from Normal mode to Low Power mode for extending battery life and switches back to Normal mode when not extending battery life. Switching of the modes is for illustrative purposes only and has no effect on the application performance. The application s status bar displays the current mode of operation (shown in Figure 2). 15

16 Power Options UI The Mobility Application Power Demo s Power Options UI provides options so users can specify when the application should switch to Low Power mode and how it should perform in Low Power mode. The power options UI is a property sheet with a Settings tab and a Low Power tab. This property sheet is accessible from Options\Power menu as shown in Figure 3 below. 16

17 Settings Tab The Settings tab shown in Figure 4 below allows users to set conditions on when to switch the application to Low Power mode. The application switches to Low Power mode when the system is battery powered and when all the conditions in this tab are met. The conditions are: Switch the application to Low Power mode when the current battery power level falls below a specified threshold. Switch the application to Low Power mode either for all power schemes or when the current system power scheme matches a selected power scheme. In addition, the Settings tab displays system power status information like current power source, percentage of remaining battery power, remaining battery time, and current power scheme. 17

18 Low Power Tab The Low Power tab shown in Figure 5 below allows users to specify how the application should perform in Low Power mode. The options in this tab are the performance/quality of features to reduce and the background activities to turn off for extending battery life. The options are for illustrative purposes only and have no effect on the performance of the Mobility Application Power Demo. The Low Power tab options include: In Low Power mode, the option to reduce video playback quality. In Low Power mode, the option to increase the time interval for information updates from the Web. In Low Power mode, the option to turn off specific application features. 18

19 Handling system sleep/wake power transitions The Mobility Application Power Demo simulates support for handling system sleep/wake power transitions by displaying status messages (shown in figures 6 & 7 below) indicating preparation for suspend and resume operations. The status messages are for illustrative purposes only, for a good user experience applications should handle system sleep/wake power transitions transparently without displaying any messages Installation The link for downloading the Mobility Application Power Demo is available in Appendix A. The download includes the Mobility Application Power Demo executable (pwrdemo.exe) and its eadme file (ead Me.htm). Install the Mobility Application Power Demo on the target system and double click the executable to start the application. No additional libraries or DLLs are required. The system requirement for running the Mobility Application Power Demo is: A battery powered notebook 1 running on Windows* (98, 98SE, ME, 2K or XP) operating system Source Code The link for downloading the Mobility Application Power Demo s source code is in Appendix A. The download includes all the source files and the design notes (Design Notes.htm) for the application. The design notes provide a brief overview on the contents of the source files. The Mobility Application Power Demo is written in C++ and uses the Microsoft* Foundation Classes (MFC) application framework library. To build the application use Visual Studio 6.0 IDE. 1 [Note - The application does run on desktops and notebooks without battery, but you will not be able to see how the application switches between Normal and Low Power modes.] 19

20 5. Conclusion As outlined in this white paper, it is fairly straightforward to implement Application Power Management for Mobility within applications. emember the following steps when implementing Application Power Management for Mobility: Identify the application performance/quality features to reduce and the application background activities to turn off for extended battery life. Identify the issues causing the application to, require a restart, lose data or change state during system sleep/wake power transitions. Identify application activities that the operating system doesn t detect. eview the Microsoft* Windows* Power Management APIs and Messages section in this white paper. Use the Intel Mobility Application Power Demo application and its source code as a reference during your design and development. Implement a UI so users can specify when and how to reduce performance/quality of features and /or turn off background activities for extended battery life. Implement application logic to extend battery life, to handle system sleep/wake power transitions, and to prevent the system from transitioning to sleep mode when the application is performing activities that the operating system doesn t detect. 20

21 Appendix A: Intel Mobility Application Power Demo Executable and Source Code Intel Mobility Application Power Demo executable is available at: Intel Mobility Application Power Demo source code is available at: 21