power.h
Go to the documentation of this file.
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  */
64  POWER_HINT_LOW_POWER = 0x00000005,
66  POWER_HINT_VR_MODE = 0x00000007
67 } power_hint_t;
68 
69 typedef enum {
71 } feature_t;
72 
73 /*
74  * Platform-level sleep state stats:
75  * power_state_voter_t struct is useful for describing the individual voters when a
76  * Platform-level sleep state is chosen by aggregation of votes from multiple
77  * clients/system conditions.
78  *
79  * This helps in attirbuting what in the device is blocking the device from
80  * entering the lowest Platform-level sleep state.
81  */
82 typedef struct {
83  /*
84  * Name of the voter.
85  */
87 
88  /*
89  * Total time in msec the voter voted for the platform sleep state since boot.
90  */
92 
93  /*
94  * Number of times the voter voted for the platform sleep state since boot.
95  */
98 
99 /*
100  * Platform-level sleep state stats:
101  * power_state_platform_sleep_state_t represents the Platform-level sleep state the
102  * device is capable of getting into.
103  *
104  * SoCs usually have more than one Platform-level sleep state.
105  *
106  * The caller calls the get_number_of_platform_modes function to figure out the size
107  * of power_state_platform_sleep_state_t array where each array element represents
108  * a specific Platform-level sleep state.
109  *
110  * Higher the index deeper the state is i.e. lesser steady-state power is consumed
111  * by the platform to be resident in that state.
112  *
113  * Caller allocates power_state_voter_t *voters for each Platform-level sleep state by
114  * calling get_voter_list.
115  */
116 typedef struct {
117  /*
118  * Platform-level Sleep state name.
119  */
121 
122  /*
123  * Time spent in msec at this platform-level sleep state since boot.
124  */
126 
127  /*
128  * Total number of times system entered this state.
129  */
131 
132  /*
133  * This platform-level sleep state can only be reached during system suspend.
134  */
136 
137  /*
138  * The following fields are useful if the Platform-level sleep state
139  * is chosen by aggregation votes from multiple clients/system conditions.
140  * All the voters have to say yes or all the system conditions need to be
141  * met to enter a platform-level sleep state.
142  *
143  * Setting number_of_voters to zero implies either the info is not available
144  * or the system does not follow a voting mechanism to choose this
145  * Platform-level sleep state.
146  */
148 
149  /*
150  * Voter list - Has to be allocated by the caller.
151  *
152  * Caller allocates power_state_voter_t *voters for each Platform-level sleep state
153  * by calling get_voter_list.
154  */
157 
158 /**
159  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
160  * and the fields of this data structure must begin with hw_module_t
161  * followed by module specific information.
162  */
163 typedef struct power_module {
165 
166  /*
167  * (*init)() performs power management setup actions at runtime
168  * startup, such as to set default cpufreq parameters. This is
169  * called only by the Power HAL instance loaded by
170  * PowerManagerService.
171  *
172  * Platform-level sleep state stats:
173  * Can Also be used to initiate device specific Platform-level
174  * Sleep state nodes from version 0.5 onwards.
175  */
176  void (*init)(struct power_module *module);
177 
178  /*
179  * (*setInteractive)() performs power management actions upon the
180  * system entering interactive state (that is, the system is awake
181  * and ready for interaction, often with UI devices such as
182  * display and touchscreen enabled) or non-interactive state (the
183  * system appears asleep, display usually turned off). The
184  * non-interactive state is usually entered after a period of
185  * inactivity, in order to conserve battery power during
186  * such inactive periods.
187  *
188  * Typical actions are to turn on or off devices and adjust
189  * cpufreq parameters. This function may also call the
190  * appropriate interfaces to allow the kernel to suspend the
191  * system to low-power sleep state when entering non-interactive
192  * state, and to disallow low-power suspend when the system is in
193  * interactive state. When low-power suspend state is allowed, the
194  * kernel may suspend the system whenever no wakelocks are held.
195  *
196  * on is non-zero when the system is transitioning to an
197  * interactive / awake state, and zero when transitioning to a
198  * non-interactive / asleep state.
199  *
200  * This function is called to enter non-interactive state after
201  * turning off the screen (if present), and called to enter
202  * interactive state prior to turning on the screen.
203  */
204  void (*setInteractive)(struct power_module *module, int on);
205 
206  /*
207  * (*powerHint) is called to pass hints on power requirements, which
208  * may result in adjustment of power/performance parameters of the
209  * cpufreq governor and other controls. The possible hints are:
210  *
211  * POWER_HINT_VSYNC
212  *
213  * Foreground app has started or stopped requesting a VSYNC pulse
214  * from SurfaceFlinger. If the app has started requesting VSYNC
215  * then CPU and GPU load is expected soon, and it may be appropriate
216  * to raise speeds of CPU, memory bus, etc. The data parameter is
217  * non-zero to indicate VSYNC pulse is now requested, or zero for
218  * VSYNC pulse no longer requested.
219  *
220  * POWER_HINT_INTERACTION
221  *
222  * User is interacting with the device, for example, touchscreen
223  * events are incoming. CPU and GPU load may be expected soon,
224  * and it may be appropriate to raise speeds of CPU, memory bus,
225  * etc. The data parameter is the estimated length of the interaction
226  * in milliseconds, or 0 if unknown.
227  *
228  * POWER_HINT_LOW_POWER
229  *
230  * Low power mode is activated or deactivated. Low power mode
231  * is intended to save battery at the cost of performance. The data
232  * parameter is non-zero when low power mode is activated, and zero
233  * when deactivated.
234  *
235  * POWER_HINT_SUSTAINED_PERFORMANCE
236  *
237  * Sustained Performance mode is actived or deactivated. Sustained
238  * performance mode is intended to provide a consistent level of
239  * performance for a prolonged amount of time. The data parameter is
240  * non-zero when sustained performance mode is activated, and zero
241  * when deactivated.
242  *
243  * POWER_HINT_VR_MODE
244  *
245  * VR Mode is activated or deactivated. VR mode is intended to
246  * provide minimum guarantee for performance for the amount of time the
247  * device can sustain it. The data parameter is non-zero when the mode
248  * is activated and zero when deactivated.
249  *
250  * A particular platform may choose to ignore any hint.
251  *
252  * availability: version 0.2
253  *
254  */
255  void (*powerHint)(struct power_module *module, power_hint_t hint,
256  void *data);
257 
258  /*
259  * (*setFeature) is called to turn on or off a particular feature
260  * depending on the state parameter. The possible features are:
261  *
262  * FEATURE_DOUBLE_TAP_TO_WAKE
263  *
264  * Enabling/Disabling this feature will allow/disallow the system
265  * to wake up by tapping the screen twice.
266  *
267  * availability: version 0.3
268  *
269  */
270  void (*setFeature)(struct power_module *module, feature_t feature, int state);
271 
272  /*
273  * Platform-level sleep state stats:
274  * Report cumulative info on the statistics on platform-level sleep states since boot.
275  *
276  * Caller of the function queries the get_number_of_sleep_states and allocates the
277  * memory for the power_state_platform_sleep_state_t *list before calling this function.
278  *
279  * power_stats module is responsible to assign values to all the fields as
280  * necessary.
281  *
282  * Higher the index deeper the state is i.e. lesser steady-state power is consumed
283  * by the platform to be resident in that state.
284  *
285  * The function returns 0 on success or negative value -errno on error.
286  * EINVAL - *list is NULL.
287  * EIO - filesystem nodes access error.
288  *
289  * availability: version 0.5
290  */
293 
294  /*
295  * Platform-level sleep state stats:
296  * This function is called to determine the number of platform-level sleep states
297  * for get_platform_low_power_stats.
298  *
299  * The value returned by this function is used to allocate memory for
300  * power_state_platform_sleep_state_t *list for get_platform_low_power_stats.
301  *
302  * The number of parameters must not change for successive calls.
303  *
304  * Return number of parameters on success or negative value -errno on error.
305  * EIO - filesystem nodes access error.
306  *
307  * availability: version 0.5
308  */
309  ssize_t (*get_number_of_platform_modes)(struct power_module *module);
310 
311  /*
312  * Platform-level sleep state stats:
313  * Provides the number of voters for each of the Platform-level sleep state.
314  *
315  * Caller uses this function to allocate memory for the power_state_voter_t list.
316  *
317  * Caller has to allocate the space for the *voter array which is
318  * get_number_of_platform_modes() long.
319  *
320  * Return 0 on success or negative value -errno on error.
321  * EINVAL - *voter is NULL.
322  * EIO - filesystem nodes access error.
323  *
324  * availability: version 0.5
325  */
326  int (*get_voter_list)(struct power_module *module, size_t *voter);
327 
329 
330 
331 __END_DECLS
332 
333 #endif // ANDROID_INCLUDE_HARDWARE_POWER_H
feature_t
Definition: power.h:69
power_state_voter_t * voters
Definition: power.h:155
uint64_t total_time_in_msec_voted_for_since_boot
Definition: power.h:91
void(* powerHint)(struct power_module *module, power_hint_t hint, void *data)
Definition: power.h:255
int(* get_voter_list)(struct power_module *module, size_t *voter)
Definition: power.h:326
void(* setInteractive)(struct power_module *module, int on)
Definition: power.h:204
uint64_t total_number_of_times_voted_since_boot
Definition: power.h:96
#define POWER_STATE_VOTER_NAME_MAX_LENGTH
Definition: power.h:50
void(* setFeature)(struct power_module *module, feature_t feature, int state)
Definition: power.h:270
void(* init)(struct power_module *module)
Definition: power.h:176
struct power_module power_module_t
power_hint_t
Definition: power.h:56
struct hw_module_t common
Definition: power.h:164
#define POWER_STATE_NAME_MAX_LENGTH
Definition: power.h:44
int(* get_platform_low_power_stats)(struct power_module *module, power_state_platform_sleep_state_t *list)
Definition: power.h:291
ssize_t(* get_number_of_platform_modes)(struct power_module *module)
Definition: power.h:309