1 /*
2 * cpuidle.h - a generic framework for CPU idle power management
3 *
4 * (C) 2007 Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
5 * Shaohua Li <shaohua.li@intel.com>
6 * Adam Belay <abelay@novell.com>
7 *
8 * This code is licenced under the GPL.
9 */
10
11 #ifndef _LINUX_CPUIDLE_H
12 #define _LINUX_CPUIDLE_H
13
14 #include <linux/percpu.h>
15 #include <linux/list.h>
16 #include <linux/hrtimer.h>
17 #include <linux/context_tracking.h>
18 #include <linux/android_kabi.h>
19
20 #define CPUIDLE_STATE_MAX 10
21 #define CPUIDLE_NAME_LEN 16
22 #define CPUIDLE_DESC_LEN 32
23
24 struct module;
25
26 struct cpuidle_device;
27 struct cpuidle_driver;
28
29
30 /****************************
31 * CPUIDLE DEVICE INTERFACE *
32 ****************************/
33
34 #define CPUIDLE_STATE_DISABLED_BY_USER BIT(0)
35 #define CPUIDLE_STATE_DISABLED_BY_DRIVER BIT(1)
36
37 struct cpuidle_state_usage {
38 unsigned long long disable;
39 unsigned long long usage;
40 u64 time_ns;
41 unsigned long long above; /* Number of times it's been too deep */
42 unsigned long long below; /* Number of times it's been too shallow */
43 unsigned long long rejected; /* Number of times idle entry was rejected */
44 #ifdef CONFIG_SUSPEND
45 unsigned long long s2idle_usage;
46 unsigned long long s2idle_time; /* in US */
47 #endif
48 };
49
50 struct cpuidle_state {
51 char name[CPUIDLE_NAME_LEN];
52 char desc[CPUIDLE_DESC_LEN];
53
54 s64 exit_latency_ns;
55 s64 target_residency_ns;
56 unsigned int flags;
57 unsigned int exit_latency; /* in US */
58 int power_usage; /* in mW */
59 unsigned int target_residency; /* in US */
60
61 int (*enter) (struct cpuidle_device *dev,
62 struct cpuidle_driver *drv,
63 int index);
64
65 int (*enter_dead) (struct cpuidle_device *dev, int index);
66
67 /*
68 * CPUs execute ->enter_s2idle with the local tick or entire timekeeping
69 * suspended, so it must not re-enable interrupts at any point (even
70 * temporarily) or attempt to change states of clock event devices.
71 *
72 * This callback may point to the same function as ->enter if all of
73 * the above requirements are met by it.
74 */
75 int (*enter_s2idle)(struct cpuidle_device *dev,
76 struct cpuidle_driver *drv,
77 int index);
78 };
79
80 /* Idle State Flags */
81 #define CPUIDLE_FLAG_NONE (0x00)
82 #define CPUIDLE_FLAG_POLLING BIT(0) /* polling state */
83 #define CPUIDLE_FLAG_COUPLED BIT(1) /* state applies to multiple cpus */
84 #define CPUIDLE_FLAG_TIMER_STOP BIT(2) /* timer is stopped on this state */
85 #define CPUIDLE_FLAG_UNUSABLE BIT(3) /* avoid using this state */
86 #define CPUIDLE_FLAG_OFF BIT(4) /* disable this state by default */
87 #define CPUIDLE_FLAG_TLB_FLUSHED BIT(5) /* idle-state flushes TLBs */
88 #define CPUIDLE_FLAG_RCU_IDLE BIT(6) /* idle-state takes care of RCU */
89
90 struct cpuidle_device_kobj;
91 struct cpuidle_state_kobj;
92 struct cpuidle_driver_kobj;
93
94 struct cpuidle_device {
95 unsigned int registered:1;
96 unsigned int enabled:1;
97 unsigned int poll_time_limit:1;
98 unsigned int cpu;
99 ktime_t next_hrtimer;
100
101 int last_state_idx;
102 u64 last_residency_ns;
103 u64 poll_limit_ns;
104 u64 forced_idle_latency_limit_ns;
105 struct cpuidle_state_usage states_usage[CPUIDLE_STATE_MAX];
106 struct cpuidle_state_kobj *kobjs[CPUIDLE_STATE_MAX];
107 struct cpuidle_driver_kobj *kobj_driver;
108 struct cpuidle_device_kobj *kobj_dev;
109 struct list_head device_list;
110
111 #ifdef CONFIG_ARCH_NEEDS_CPU_IDLE_COUPLED
112 cpumask_t coupled_cpus;
113 struct cpuidle_coupled *coupled;
114 #endif
115
116 ANDROID_KABI_RESERVE(1);
117 };
118
119 DECLARE_PER_CPU(struct cpuidle_device *, cpuidle_devices);
120 DECLARE_PER_CPU(struct cpuidle_device, cpuidle_dev);
121
ct_cpuidle_enter(void)122 static __always_inline void ct_cpuidle_enter(void)
123 {
124 lockdep_assert_irqs_disabled();
125 /*
126 * Idle is allowed to (temporary) enable IRQs. It
127 * will return with IRQs disabled.
128 *
129 * Trace IRQs enable here, then switch off RCU, and have
130 * arch_cpu_idle() use raw_local_irq_enable(). Note that
131 * ct_idle_enter() relies on lockdep IRQ state, so switch that
132 * last -- this is very similar to the entry code.
133 */
134 trace_hardirqs_on_prepare();
135 lockdep_hardirqs_on_prepare();
136 instrumentation_end();
137 ct_idle_enter();
138 lockdep_hardirqs_on(_RET_IP_);
139 }
140
ct_cpuidle_exit(void)141 static __always_inline void ct_cpuidle_exit(void)
142 {
143 /*
144 * Carefully undo the above.
145 */
146 lockdep_hardirqs_off(_RET_IP_);
147 ct_idle_exit();
148 instrumentation_begin();
149 }
150
151 /****************************
152 * CPUIDLE DRIVER INTERFACE *
153 ****************************/
154
155 struct cpuidle_driver {
156 const char *name;
157 struct module *owner;
158
159 /* used by the cpuidle framework to setup the broadcast timer */
160 unsigned int bctimer:1;
161 /* states array must be ordered in decreasing power consumption */
162 struct cpuidle_state states[CPUIDLE_STATE_MAX];
163 int state_count;
164 int safe_state_index;
165
166 /* the driver handles the cpus in cpumask */
167 struct cpumask *cpumask;
168
169 /* preferred governor to switch at register time */
170 const char *governor;
171
172 ANDROID_KABI_RESERVE(1);
173 };
174
175 #ifdef CONFIG_CPU_IDLE
176 extern void disable_cpuidle(void);
177 extern bool cpuidle_not_available(struct cpuidle_driver *drv,
178 struct cpuidle_device *dev);
179
180 extern int cpuidle_select(struct cpuidle_driver *drv,
181 struct cpuidle_device *dev,
182 bool *stop_tick);
183 extern int cpuidle_enter(struct cpuidle_driver *drv,
184 struct cpuidle_device *dev, int index);
185 extern void cpuidle_reflect(struct cpuidle_device *dev, int index);
186 extern u64 cpuidle_poll_time(struct cpuidle_driver *drv,
187 struct cpuidle_device *dev);
188
189 extern int cpuidle_register_driver(struct cpuidle_driver *drv);
190 extern struct cpuidle_driver *cpuidle_get_driver(void);
191 extern void cpuidle_driver_state_disabled(struct cpuidle_driver *drv, int idx,
192 bool disable);
193 extern void cpuidle_unregister_driver(struct cpuidle_driver *drv);
194 extern int cpuidle_register_device(struct cpuidle_device *dev);
195 extern void cpuidle_unregister_device(struct cpuidle_device *dev);
196 extern int cpuidle_register(struct cpuidle_driver *drv,
197 const struct cpumask *const coupled_cpus);
198 extern void cpuidle_unregister(struct cpuidle_driver *drv);
199 extern void cpuidle_pause_and_lock(void);
200 extern void cpuidle_resume_and_unlock(void);
201 extern void cpuidle_pause(void);
202 extern void cpuidle_resume(void);
203 extern int cpuidle_enable_device(struct cpuidle_device *dev);
204 extern void cpuidle_disable_device(struct cpuidle_device *dev);
205 extern int cpuidle_play_dead(void);
206
207 extern struct cpuidle_driver *cpuidle_get_cpu_driver(struct cpuidle_device *dev);
cpuidle_get_device(void)208 static inline struct cpuidle_device *cpuidle_get_device(void)
209 {return __this_cpu_read(cpuidle_devices); }
210 #else
disable_cpuidle(void)211 static inline void disable_cpuidle(void) { }
cpuidle_not_available(struct cpuidle_driver * drv,struct cpuidle_device * dev)212 static inline bool cpuidle_not_available(struct cpuidle_driver *drv,
213 struct cpuidle_device *dev)
214 {return true; }
cpuidle_select(struct cpuidle_driver * drv,struct cpuidle_device * dev,bool * stop_tick)215 static inline int cpuidle_select(struct cpuidle_driver *drv,
216 struct cpuidle_device *dev, bool *stop_tick)
217 {return -ENODEV; }
cpuidle_enter(struct cpuidle_driver * drv,struct cpuidle_device * dev,int index)218 static inline int cpuidle_enter(struct cpuidle_driver *drv,
219 struct cpuidle_device *dev, int index)
220 {return -ENODEV; }
cpuidle_reflect(struct cpuidle_device * dev,int index)221 static inline void cpuidle_reflect(struct cpuidle_device *dev, int index) { }
cpuidle_poll_time(struct cpuidle_driver * drv,struct cpuidle_device * dev)222 static inline u64 cpuidle_poll_time(struct cpuidle_driver *drv,
223 struct cpuidle_device *dev)
224 {return 0; }
cpuidle_register_driver(struct cpuidle_driver * drv)225 static inline int cpuidle_register_driver(struct cpuidle_driver *drv)
226 {return -ENODEV; }
cpuidle_get_driver(void)227 static inline struct cpuidle_driver *cpuidle_get_driver(void) {return NULL; }
cpuidle_driver_state_disabled(struct cpuidle_driver * drv,int idx,bool disable)228 static inline void cpuidle_driver_state_disabled(struct cpuidle_driver *drv,
229 int idx, bool disable) { }
cpuidle_unregister_driver(struct cpuidle_driver * drv)230 static inline void cpuidle_unregister_driver(struct cpuidle_driver *drv) { }
cpuidle_register_device(struct cpuidle_device * dev)231 static inline int cpuidle_register_device(struct cpuidle_device *dev)
232 {return -ENODEV; }
cpuidle_unregister_device(struct cpuidle_device * dev)233 static inline void cpuidle_unregister_device(struct cpuidle_device *dev) { }
cpuidle_register(struct cpuidle_driver * drv,const struct cpumask * const coupled_cpus)234 static inline int cpuidle_register(struct cpuidle_driver *drv,
235 const struct cpumask *const coupled_cpus)
236 {return -ENODEV; }
cpuidle_unregister(struct cpuidle_driver * drv)237 static inline void cpuidle_unregister(struct cpuidle_driver *drv) { }
cpuidle_pause_and_lock(void)238 static inline void cpuidle_pause_and_lock(void) { }
cpuidle_resume_and_unlock(void)239 static inline void cpuidle_resume_and_unlock(void) { }
cpuidle_pause(void)240 static inline void cpuidle_pause(void) { }
cpuidle_resume(void)241 static inline void cpuidle_resume(void) { }
cpuidle_enable_device(struct cpuidle_device * dev)242 static inline int cpuidle_enable_device(struct cpuidle_device *dev)
243 {return -ENODEV; }
cpuidle_disable_device(struct cpuidle_device * dev)244 static inline void cpuidle_disable_device(struct cpuidle_device *dev) { }
cpuidle_play_dead(void)245 static inline int cpuidle_play_dead(void) {return -ENODEV; }
cpuidle_get_cpu_driver(struct cpuidle_device * dev)246 static inline struct cpuidle_driver *cpuidle_get_cpu_driver(
247 struct cpuidle_device *dev) {return NULL; }
cpuidle_get_device(void)248 static inline struct cpuidle_device *cpuidle_get_device(void) {return NULL; }
249 #endif
250
251 #ifdef CONFIG_CPU_IDLE
252 extern int cpuidle_find_deepest_state(struct cpuidle_driver *drv,
253 struct cpuidle_device *dev,
254 u64 latency_limit_ns);
255 extern int cpuidle_enter_s2idle(struct cpuidle_driver *drv,
256 struct cpuidle_device *dev);
257 extern void cpuidle_use_deepest_state(u64 latency_limit_ns);
258 #else
cpuidle_find_deepest_state(struct cpuidle_driver * drv,struct cpuidle_device * dev,u64 latency_limit_ns)259 static inline int cpuidle_find_deepest_state(struct cpuidle_driver *drv,
260 struct cpuidle_device *dev,
261 u64 latency_limit_ns)
262 {return -ENODEV; }
cpuidle_enter_s2idle(struct cpuidle_driver * drv,struct cpuidle_device * dev)263 static inline int cpuidle_enter_s2idle(struct cpuidle_driver *drv,
264 struct cpuidle_device *dev)
265 {return -ENODEV; }
cpuidle_use_deepest_state(u64 latency_limit_ns)266 static inline void cpuidle_use_deepest_state(u64 latency_limit_ns)
267 {
268 }
269 #endif
270
271 /* kernel/sched/idle.c */
272 extern void sched_idle_set_state(struct cpuidle_state *idle_state);
273 extern void default_idle_call(void);
274
275 #ifdef CONFIG_ARCH_NEEDS_CPU_IDLE_COUPLED
276 void cpuidle_coupled_parallel_barrier(struct cpuidle_device *dev, atomic_t *a);
277 #else
cpuidle_coupled_parallel_barrier(struct cpuidle_device * dev,atomic_t * a)278 static inline void cpuidle_coupled_parallel_barrier(struct cpuidle_device *dev, atomic_t *a)
279 {
280 }
281 #endif
282
283 #if defined(CONFIG_CPU_IDLE) && defined(CONFIG_ARCH_HAS_CPU_RELAX)
284 void cpuidle_poll_state_init(struct cpuidle_driver *drv);
285 #else
cpuidle_poll_state_init(struct cpuidle_driver * drv)286 static inline void cpuidle_poll_state_init(struct cpuidle_driver *drv) {}
287 #endif
288
289 /******************************
290 * CPUIDLE GOVERNOR INTERFACE *
291 ******************************/
292
293 struct cpuidle_governor {
294 char name[CPUIDLE_NAME_LEN];
295 struct list_head governor_list;
296 unsigned int rating;
297
298 int (*enable) (struct cpuidle_driver *drv,
299 struct cpuidle_device *dev);
300 void (*disable) (struct cpuidle_driver *drv,
301 struct cpuidle_device *dev);
302
303 int (*select) (struct cpuidle_driver *drv,
304 struct cpuidle_device *dev,
305 bool *stop_tick);
306 void (*reflect) (struct cpuidle_device *dev, int index);
307 };
308
309 extern int cpuidle_register_governor(struct cpuidle_governor *gov);
310 extern s64 cpuidle_governor_latency_req(unsigned int cpu);
311
312 #define __CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, \
313 idx, \
314 state, \
315 is_retention, is_rcu) \
316 ({ \
317 int __ret = 0; \
318 \
319 if (!idx) { \
320 cpu_do_idle(); \
321 return idx; \
322 } \
323 \
324 if (!is_retention) \
325 __ret = cpu_pm_enter(); \
326 if (!__ret) { \
327 if (!is_rcu) \
328 ct_cpuidle_enter(); \
329 __ret = low_level_idle_enter(state); \
330 if (!is_rcu) \
331 ct_cpuidle_exit(); \
332 if (!is_retention) \
333 cpu_pm_exit(); \
334 } \
335 \
336 __ret ? -1 : idx; \
337 })
338
339 #define CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, idx) \
340 __CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, idx, idx, 0, 0)
341
342 #define CPU_PM_CPU_IDLE_ENTER_RETENTION(low_level_idle_enter, idx) \
343 __CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, idx, idx, 1, 0)
344
345 #define CPU_PM_CPU_IDLE_ENTER_PARAM(low_level_idle_enter, idx, state) \
346 __CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, idx, state, 0, 0)
347
348 #define CPU_PM_CPU_IDLE_ENTER_PARAM_RCU(low_level_idle_enter, idx, state) \
349 __CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, idx, state, 0, 1)
350
351 #define CPU_PM_CPU_IDLE_ENTER_RETENTION_PARAM(low_level_idle_enter, idx, state) \
352 __CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, idx, state, 1, 0)
353
354 #define CPU_PM_CPU_IDLE_ENTER_RETENTION_PARAM_RCU(low_level_idle_enter, idx, state) \
355 __CPU_PM_CPU_IDLE_ENTER(low_level_idle_enter, idx, state, 1, 1)
356
357 #endif /* _LINUX_CPUIDLE_H */
358