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 <stdint.h> 21 #include <sys/cdefs.h> 22 #include <sys/types.h> 23 24 #include <hardware/hardware.h> 25 26 __BEGIN_DECLS 27 28 #define POWER_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 29 #define POWER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) 30 #define POWER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) 31 32 /** 33 * The id of this module 34 */ 35 #define POWER_HARDWARE_MODULE_ID "power" 36 37 /* 38 * Power hint identifiers passed to (*powerHint) 39 */ 40 41 typedef enum { 42 POWER_HINT_VSYNC = 0x00000001, 43 POWER_HINT_INTERACTION = 0x00000002, 44 /* DO NOT USE POWER_HINT_VIDEO_ENCODE/_DECODE! They will be removed in 45 * KLP. 46 */ 47 POWER_HINT_VIDEO_ENCODE = 0x00000003, 48 POWER_HINT_VIDEO_DECODE = 0x00000004, 49 POWER_HINT_LOW_POWER = 0x00000005 50 } power_hint_t; 51 52 typedef enum { 53 POWER_FEATURE_DOUBLE_TAP_TO_WAKE = 0x00000001 54 } feature_t; 55 56 /** 57 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 58 * and the fields of this data structure must begin with hw_module_t 59 * followed by module specific information. 60 */ 61 typedef struct power_module { 62 struct hw_module_t common; 63 64 /* 65 * (*init)() performs power management setup actions at runtime 66 * startup, such as to set default cpufreq parameters. This is 67 * called only by the Power HAL instance loaded by 68 * PowerManagerService. 69 */ 70 void (*init)(struct power_module *module); 71 72 /* 73 * (*setInteractive)() performs power management actions upon the 74 * system entering interactive state (that is, the system is awake 75 * and ready for interaction, often with UI devices such as 76 * display and touchscreen enabled) or non-interactive state (the 77 * system appears asleep, display usually turned off). The 78 * non-interactive state is usually entered after a period of 79 * inactivity, in order to conserve battery power during 80 * such inactive periods. 81 * 82 * Typical actions are to turn on or off devices and adjust 83 * cpufreq parameters. This function may also call the 84 * appropriate interfaces to allow the kernel to suspend the 85 * system to low-power sleep state when entering non-interactive 86 * state, and to disallow low-power suspend when the system is in 87 * interactive state. When low-power suspend state is allowed, the 88 * kernel may suspend the system whenever no wakelocks are held. 89 * 90 * on is non-zero when the system is transitioning to an 91 * interactive / awake state, and zero when transitioning to a 92 * non-interactive / asleep state. 93 * 94 * This function is called to enter non-interactive state after 95 * turning off the screen (if present), and called to enter 96 * interactive state prior to turning on the screen. 97 */ 98 void (*setInteractive)(struct power_module *module, int on); 99 100 /* 101 * (*powerHint) is called to pass hints on power requirements, which 102 * may result in adjustment of power/performance parameters of the 103 * cpufreq governor and other controls. The possible hints are: 104 * 105 * POWER_HINT_VSYNC 106 * 107 * Foreground app has started or stopped requesting a VSYNC pulse 108 * from SurfaceFlinger. If the app has started requesting VSYNC 109 * then CPU and GPU load is expected soon, and it may be appropriate 110 * to raise speeds of CPU, memory bus, etc. The data parameter is 111 * non-zero to indicate VSYNC pulse is now requested, or zero for 112 * VSYNC pulse no longer requested. 113 * 114 * POWER_HINT_INTERACTION 115 * 116 * User is interacting with the device, for example, touchscreen 117 * events are incoming. CPU and GPU load may be expected soon, 118 * and it may be appropriate to raise speeds of CPU, memory bus, 119 * etc. The data parameter is unused. 120 * 121 * POWER_HINT_LOW_POWER 122 * 123 * Low power mode is activated or deactivated. Low power mode 124 * is intended to save battery at the cost of performance. The data 125 * parameter is non-zero when low power mode is activated, and zero 126 * when deactivated. 127 * 128 * A particular platform may choose to ignore any hint. 129 * 130 * availability: version 0.2 131 * 132 */ 133 void (*powerHint)(struct power_module *module, power_hint_t hint, 134 void *data); 135 136 /* 137 * (*setFeature) is called to turn on or off a particular feature 138 * depending on the state parameter. The possible features are: 139 * 140 * FEATURE_DOUBLE_TAP_TO_WAKE 141 * 142 * Enabling/Disabling this feature will allow/disallow the system 143 * to wake up by tapping the screen twice. 144 * 145 * availability: version 0.3 146 * 147 */ 148 void (*setFeature)(struct power_module *module, feature_t feature, int state); 149 150 } power_module_t; 151 152 153 __END_DECLS 154 155 #endif // ANDROID_INCLUDE_HARDWARE_POWER_H 156