SLP_pm_PG.h

   1 /*
   2  *  libslp-pm
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: DongGi Jang <dg0402.jang@samsung.com>
   7  *
   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
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  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.
  19  *
  20 */
  21
  22
  23 /**
  24  *
  25  * @ingroup SLP_PG
  26  * @defgroup SLP_PG_PM Power Manager
  27  * @{
  28
  29 <h1 class="pg">Introduction</h1>
  30
  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.
  34
  35 <h2 class="pg">Scope</h2>
  36 The scope of this document is limited to Power Manager API usage.
  37
  38 <br>
  39 <h1 class="pg">Power Manager Architecture</h1>
  40 The Power Manager (PM) consists of a client API library and a Power Manager daemon.
  41
  42 <h3 class="pg" align="center">Power Manager Architecture</h3>
  43 @image html SLP_pm_PG_architecture.png
  44 <br>
  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.
  48
  49 <h3 class="pg" align="center">Power Manager State Diagram</h3>
  50 @image html SLP_pm_PG_state_diagram.png
  51
  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.
  55
  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.
  62
  63 <h1 class="pg">Power Manager Funtions</h1>
  64
  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.
  75 <br><br>
  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.
  87 <br><br>
  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.
  93
  94 <b>Power state:</b>
  95 @code
  96 // POWER STATES
  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
 101 @endcode
 102
 103 <h2 class="pg">Sample Code</h2>
 104 @code
 105 #include <pmapi.h>
 106 int main()
 107 {
 108         int result;
 109
 110         // Lock current state as LCD_NORMAL
 111         result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, 0);
 112         if( result < 0 ) {
 113                 printf("[ERROR] return value result =%d, \n",result);
 114         }
 115         else
 116                 printf("[SUCCESS]return value result =%d \n",result);
 117
 118         // Do something here
 119
 120         //Un-lock NORMAL state so that power state change can occur with system-events
 121
 122         result = pm_unlock_state(LCD_NORMAL, PM_RESET_TIMER);
 123         if( result < 0 ) {
 124                 printf("[ERROR] return value result =%d, \n",result);
 125         }
 126         else
 127                 printf("[SUCCESS]return value result =%d \n",result);
 128
 129         // change the state into LCD ON
 130         result = pm_change_state(LCD_NORMAL);
 131         if( result < 0 )
 132                 printf("[ERROR] return value result =%d, \n",result);
 133         else
 134                 printf("[SUCCESS]return value result =%d \n",result);
 135
 136         return 0;
 137 }
 138 @endcode
 139
 140  @}
 141 **/