4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: DongGi Jang <dg0402.jang@samsung.com>
8 * Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
26 * @defgroup SLP_PG_PM Power Manager
29 <h1 class="pg">Introduction</h1>
31 <h2 class="pg">Purpose</h2>
32 The purpose of this document is to describe how applications can use Power Manager APIs to save system power consumption.
33 This document gives programming guidelines to application engineers.
35 <h2 class="pg">Scope</h2>
36 The scope of this document is limited to Power Manager API usage.
39 <h1 class="pg">Power Manager Architecture</h1>
40 The Power Manager (PM) consists of a client API library and a Power Manager daemon.
42 <h3 class="pg" align="center">Power Manager Architecture</h3>
43 @image html SLP_pm_PG_architecture.png
45 Power Manager daemon controls a kernel power management module and peripheral device drivers to save system power consumption.
46 It manages the system power states and makes state transitions according to the events. <br>
47 There are four power states ? Normal (i.e. LCD on), LCD dimming, LCD off and Sleep.
49 <h3 class="pg" align="center">Power Manager State Diagram</h3>
50 @image html SLP_pm_PG_state_diagram.png
52 Applications can put conditions on specific state transitions. For example, Video Player applications do not want the Power Manager
53 to allow the LCD to be in a dimming state or to turn off the LCD backlight.
54 For this purpose, Video Player applications can use Power Manager APIs to send the condition to Power Manager.
56 <h1 class="pg">Power Manager Features</h1>
57 - There are four power states, Normal(i.e. LCD on), LCD dimming, LCD off and Sleep.
58 - If there is no user input for a certain time, PM changes the state of PM to a state that has lower power consumption.
59 - When user input or another system interrupt occurs, PM rolls the state back immediately.
60 - However, some applications may want PM not to change the state, for example music players that do not want to suspend,
61 can sustain PM in the state required by using the pm_lock_power_state() API.
63 <h1 class="pg">Power Manager Funtions</h1>
65 <h2 class="pg">Power Manager API Introduction</h2>
66 <i><b>API : pm_lock_state</b></i>
67 <br><b>Parameter In :</b> unsigned int state, unsigned int flag, unsigned int timeout
68 <br><b>Return :</b> int
69 <br><b>Functionality :</b> This API is used to lock a particular power-state as the current power-state.<br>
70 The parameter state specifies the power state which you want to lock LCD_NORMAL, LCD_DIM, LCD_OFF. \n
71 The second parameter Flag is set if you want to go the requested lock state directly.\n
72 The third parameter timeout specifies lock-timeout in milliseconds.
73 If the value 0 is selected, the power state remains locked until pm_unlock_state is called.<br>
74 This function returns 0 on success and a negative value (-1) on failure.
76 <i><b>API : pm_unlock_state</b></i>
77 <br><b>Parameter In :</b> unsigned int state, unsigned int flag
78 <br><b>Return :</b> int
79 <br><b>Functionality :</b> This API is used to Unlock the power state.<br>
80 The parameter state specifies the power state which you want to unlock .Some examples are LCD_NORMAL, LCD_DIM, LCD_OFF.<br>
81 The second parameter flag is set if you want to go to the requested state directly after unlocking. <br>
82 PM_SLEEP_MARGIN - If the current status is lcd off, power-manager reset timer to 5 second. If the current status is not lcd off, power-manager uses the existing timer. <br>
83 PM_RESET_TIMER - Power-manager resets timer. (lcd normal : reset timer to predfined value which is set in setting module, lcd dim or off : reset timer to 5 seconds)<br>
84 PM_KEEP_TIMER - Power-manager uses the existing timer (if timer is already expired, pwoer-manager changes the status) <br>
85 This is valid only when the current state transition was blocked by the locking and this function call releases the blocking.<br>
86 This function returns 0 on success and a negative value (-1) on failure.
88 <i><b>API : pm_change_state</b></i>
89 <br><b>Parameter In :</b> unsigned int (power state)
90 <br><b>Return :</b> int
91 <br><b>Functionality :</b> This API is used to change the power manager state by force.<br>
92 This function returns 0 on success, -1 if failed.
97 #define LCD_NORMAL 0x1 // NORMAL state
98 #define LCD_DIM 0x2 // LCD dimming state
99 #define LCD_OFF 0x4 // LCD off state
100 #define SUSPEND 0x8 // Sleep state
103 <h2 class="pg">Sample Code</h2>
110 // Lock current state as LCD_NORMAL
111 result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, 0);
113 printf("[ERROR] return value result =%d, \n",result);
116 printf("[SUCCESS]return value result =%d \n",result);
120 //Un-lock NORMAL state so that power state change can occur with system-events
122 result = pm_unlock_state(LCD_NORMAL, PM_RESET_TIMER);
124 printf("[ERROR] return value result =%d, \n",result);
127 printf("[SUCCESS]return value result =%d \n",result);
129 // change the state into LCD ON
130 result = pm_change_state(LCD_NORMAL);
132 printf("[ERROR] return value result =%d, \n",result);
134 printf("[SUCCESS]return value result =%d \n",result);