1 /* 2 * Copyright (C) 2012 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_INCLUDE_HARDWARE_POWER_H 18 #define ANDROID_INCLUDE_HARDWARE_POWER_H 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 #include <sys/cdefs.h> 23 #include <sys/types.h> 24 25 #include <hardware/hardware.h> 26 27 __BEGIN_DECLS 28 29 #define POWER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 30 #define POWER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) 31 #define POWER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) 32 #define POWER_MODULE_API_VERSION_0_4 HARDWARE_MODULE_API_VERSION(0, 4) 33 #define POWER_MODULE_API_VERSION_0_5 HARDWARE_MODULE_API_VERSION(0, 5) 34 35 /** 36 * The id of this module 37 */ 38 #define POWER_HARDWARE_MODULE_ID "power" 39 40 /* 41 * Platform-level sleep state stats. 42 * Maximum length of Platform-level sleep state name. 43 */ 44 #define POWER_STATE_NAME_MAX_LENGTH 100 45 46 /* 47 * Platform-level sleep state stats. 48 * Maximum length of Platform-level sleep state voter name. 49 */ 50 #define POWER_STATE_VOTER_NAME_MAX_LENGTH 100 51 52 /* 53 * Power hint identifiers passed to (*powerHint) 54 */ 55 56 typedef enum { 57 POWER_HINT_VSYNC = 0x00000001, 58 POWER_HINT_INTERACTION = 0x00000002, 59 /* DO NOT USE POWER_HINT_VIDEO_ENCODE/_DECODE! They will be removed in 60 * KLP. 61 */ 62 POWER_HINT_VIDEO_ENCODE = 0x00000003, 63 POWER_HINT_VIDEO_DECODE = 0x00000004, 64 POWER_HINT_LOW_POWER = 0x00000005, 65 POWER_HINT_SUSTAINED_PERFORMANCE = 0x00000006, 66 POWER_HINT_VR_MODE = 0x00000007, 67 POWER_HINT_LAUNCH = 0x00000008, 68 POWER_HINT_DISABLE_TOUCH = 0x00000009 69 } power_hint_t; 70 71 typedef enum { 72 POWER_FEATURE_DOUBLE_TAP_TO_WAKE = 0x00000001 73 } feature_t; 74 75 /* 76 * Platform-level sleep state stats: 77 * power_state_voter_t struct is useful for describing the individual voters when a 78 * Platform-level sleep state is chosen by aggregation of votes from multiple 79 * clients/system conditions. 80 * 81 * This helps in attirbuting what in the device is blocking the device from 82 * entering the lowest Platform-level sleep state. 83 */ 84 typedef struct { 85 /* 86 * Name of the voter. 87 */ 88 char name[POWER_STATE_VOTER_NAME_MAX_LENGTH]; 89 90 /* 91 * Total time in msec the voter voted for the platform sleep state since boot. 92 */ 93 uint64_t total_time_in_msec_voted_for_since_boot; 94 95 /* 96 * Number of times the voter voted for the platform sleep state since boot. 97 */ 98 uint64_t total_number_of_times_voted_since_boot; 99 } power_state_voter_t; 100 101 /* 102 * Platform-level sleep state stats: 103 * power_state_platform_sleep_state_t represents the Platform-level sleep state the 104 * device is capable of getting into. 105 * 106 * SoCs usually have more than one Platform-level sleep state. 107 * 108 * The caller calls the get_number_of_platform_modes function to figure out the size 109 * of power_state_platform_sleep_state_t array where each array element represents 110 * a specific Platform-level sleep state. 111 * 112 * Higher the index deeper the state is i.e. lesser steady-state power is consumed 113 * by the platform to be resident in that state. 114 * 115 * Caller allocates power_state_voter_t *voters for each Platform-level sleep state by 116 * calling get_voter_list. 117 */ 118 typedef struct { 119 /* 120 * Platform-level Sleep state name. 121 */ 122 char name[POWER_STATE_NAME_MAX_LENGTH]; 123 124 /* 125 * Time spent in msec at this platform-level sleep state since boot. 126 */ 127 uint64_t residency_in_msec_since_boot; 128 129 /* 130 * Total number of times system entered this state. 131 */ 132 uint64_t total_transitions; 133 134 /* 135 * This platform-level sleep state can only be reached during system suspend. 136 */ 137 bool supported_only_in_suspend; 138 139 /* 140 * The following fields are useful if the Platform-level sleep state 141 * is chosen by aggregation votes from multiple clients/system conditions. 142 * All the voters have to say yes or all the system conditions need to be 143 * met to enter a platform-level sleep state. 144 * 145 * Setting number_of_voters to zero implies either the info is not available 146 * or the system does not follow a voting mechanism to choose this 147 * Platform-level sleep state. 148 */ 149 uint32_t number_of_voters; 150 151 /* 152 * Voter list - Has to be allocated by the caller. 153 * 154 * Caller allocates power_state_voter_t *voters for each Platform-level sleep state 155 * by calling get_voter_list. 156 */ 157 power_state_voter_t *voters; 158 } power_state_platform_sleep_state_t; 159 160 /** 161 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 162 * and the fields of this data structure must begin with hw_module_t 163 * followed by module specific information. 164 */ 165 typedef struct power_module { 166 struct hw_module_t common; 167 168 /* 169 * (*init)() performs power management setup actions at runtime 170 * startup, such as to set default cpufreq parameters. This is 171 * called only by the Power HAL instance loaded by 172 * PowerManagerService. 173 * 174 * Platform-level sleep state stats: 175 * Can Also be used to initiate device specific Platform-level 176 * Sleep state nodes from version 0.5 onwards. 177 */ 178 void (*init)(struct power_module *module); 179 180 /* 181 * (*setInteractive)() performs power management actions upon the 182 * system entering interactive state (that is, the system is awake 183 * and ready for interaction, often with UI devices such as 184 * display and touchscreen enabled) or non-interactive state (the 185 * system appears asleep, display usually turned off). The 186 * non-interactive state is usually entered after a period of 187 * inactivity, in order to conserve battery power during 188 * such inactive periods. 189 * 190 * Typical actions are to turn on or off devices and adjust 191 * cpufreq parameters. This function may also call the 192 * appropriate interfaces to allow the kernel to suspend the 193 * system to low-power sleep state when entering non-interactive 194 * state, and to disallow low-power suspend when the system is in 195 * interactive state. When low-power suspend state is allowed, the 196 * kernel may suspend the system whenever no wakelocks are held. 197 * 198 * on is non-zero when the system is transitioning to an 199 * interactive / awake state, and zero when transitioning to a 200 * non-interactive / asleep state. 201 * 202 * This function is called to enter non-interactive state after 203 * turning off the screen (if present), and called to enter 204 * interactive state prior to turning on the screen. 205 */ 206 void (*setInteractive)(struct power_module *module, int on); 207 208 /* 209 * (*powerHint) is called to pass hints on power requirements, which 210 * may result in adjustment of power/performance parameters of the 211 * cpufreq governor and other controls. The possible hints are: 212 * 213 * POWER_HINT_VSYNC 214 * 215 * Foreground app has started or stopped requesting a VSYNC pulse 216 * from SurfaceFlinger. If the app has started requesting VSYNC 217 * then CPU and GPU load is expected soon, and it may be appropriate 218 * to raise speeds of CPU, memory bus, etc. The data parameter is 219 * non-zero to indicate VSYNC pulse is now requested, or zero for 220 * VSYNC pulse no longer requested. 221 * 222 * POWER_HINT_INTERACTION 223 * 224 * User is interacting with the device, for example, touchscreen 225 * events are incoming. CPU and GPU load may be expected soon, 226 * and it may be appropriate to raise speeds of CPU, memory bus, 227 * etc. The data parameter is the estimated length of the interaction 228 * in milliseconds, or 0 if unknown. 229 * 230 * POWER_HINT_LOW_POWER 231 * 232 * Low power mode is activated or deactivated. Low power mode 233 * is intended to save battery at the cost of performance. The data 234 * parameter is non-zero when low power mode is activated, and zero 235 * when deactivated. 236 * 237 * POWER_HINT_SUSTAINED_PERFORMANCE 238 * 239 * Sustained Performance mode is actived or deactivated. Sustained 240 * performance mode is intended to provide a consistent level of 241 * performance for a prolonged amount of time. The data parameter is 242 * non-zero when sustained performance mode is activated, and zero 243 * when deactivated. 244 * 245 * POWER_HINT_VR_MODE 246 * 247 * VR Mode is activated or deactivated. VR mode is intended to 248 * provide minimum guarantee for performance for the amount of time the 249 * device can sustain it. The data parameter is non-zero when the mode 250 * is activated and zero when deactivated. 251 * 252 * POWER_HINT_DISABLE_TOUCH 253 * 254 * When device enters some special modes, e.g. theater mode in Android 255 * Wear, there is no touch interaction expected between device and user. 256 * Touch controller could be disabled in those modes to save power. 257 * The data parameter is non-zero when touch could be disabled, and zero 258 * when touch needs to be re-enabled. 259 * 260 * A particular platform may choose to ignore any hint. 261 * 262 * availability: version 0.2 263 * 264 */ 265 void (*powerHint)(struct power_module *module, power_hint_t hint, 266 void *data); 267 268 /* 269 * (*setFeature) is called to turn on or off a particular feature 270 * depending on the state parameter. The possible features are: 271 * 272 * FEATURE_DOUBLE_TAP_TO_WAKE 273 * 274 * Enabling/Disabling this feature will allow/disallow the system 275 * to wake up by tapping the screen twice. 276 * 277 * availability: version 0.3 278 * 279 */ 280 void (*setFeature)(struct power_module *module, feature_t feature, int state); 281 282 /* 283 * Platform-level sleep state stats: 284 * Report cumulative info on the statistics on platform-level sleep states since boot. 285 * 286 * Caller of the function queries the get_number_of_sleep_states and allocates the 287 * memory for the power_state_platform_sleep_state_t *list before calling this function. 288 * 289 * power_stats module is responsible to assign values to all the fields as 290 * necessary. 291 * 292 * Higher the index deeper the state is i.e. lesser steady-state power is consumed 293 * by the platform to be resident in that state. 294 * 295 * The function returns 0 on success or negative value -errno on error. 296 * EINVAL - *list is NULL. 297 * EIO - filesystem nodes access error. 298 * 299 * availability: version 0.5 300 */ 301 int (*get_platform_low_power_stats)(struct power_module *module, 302 power_state_platform_sleep_state_t *list); 303 304 /* 305 * Platform-level sleep state stats: 306 * This function is called to determine the number of platform-level sleep states 307 * for get_platform_low_power_stats. 308 * 309 * The value returned by this function is used to allocate memory for 310 * power_state_platform_sleep_state_t *list for get_platform_low_power_stats. 311 * 312 * The number of parameters must not change for successive calls. 313 * 314 * Return number of parameters on success or negative value -errno on error. 315 * EIO - filesystem nodes access error. 316 * 317 * availability: version 0.5 318 */ 319 ssize_t (*get_number_of_platform_modes)(struct power_module *module); 320 321 /* 322 * Platform-level sleep state stats: 323 * Provides the number of voters for each of the Platform-level sleep state. 324 * 325 * Caller uses this function to allocate memory for the power_state_voter_t list. 326 * 327 * Caller has to allocate the space for the *voter array which is 328 * get_number_of_platform_modes() long. 329 * 330 * Return 0 on success or negative value -errno on error. 331 * EINVAL - *voter is NULL. 332 * EIO - filesystem nodes access error. 333 * 334 * availability: version 0.5 335 */ 336 int (*get_voter_list)(struct power_module *module, size_t *voter); 337 338 } power_module_t; 339 340 341 __END_DECLS 342 343 #endif // ANDROID_INCLUDE_HARDWARE_POWER_H 344