1 /* SPDX-License-Identifier: GPL-2.0-only */
3 * devfreq: Generic Dynamic Voltage and Frequency Scaling (DVFS) Framework
6 * Copyright (C) 2011 Samsung Electronics
7 * MyungJoo Ham <myungjoo.ham@samsung.com>
10 #ifndef __LINUX_DEVFREQ_H__
11 #define __LINUX_DEVFREQ_H__
13 #include <linux/device.h>
14 #include <linux/notifier.h>
15 #include <linux/pm_opp.h>
16 #include <linux/pm_qos.h>
18 /* DEVFREQ governor name */
19 #define DEVFREQ_GOV_SIMPLE_ONDEMAND "simple_ondemand"
20 #define DEVFREQ_GOV_PERFORMANCE "performance"
21 #define DEVFREQ_GOV_POWERSAVE "powersave"
22 #define DEVFREQ_GOV_USERSPACE "userspace"
23 #define DEVFREQ_GOV_PASSIVE "passive"
25 /* DEVFREQ notifier interface */
26 #define DEVFREQ_TRANSITION_NOTIFIER (0)
28 /* Transition notifiers of DEVFREQ_TRANSITION_NOTIFIER */
29 #define DEVFREQ_PRECHANGE (0)
30 #define DEVFREQ_POSTCHANGE (1)
32 /* DEVFREQ work timers */
34 DEVFREQ_TIMER_DEFERRABLE
= 0,
35 DEVFREQ_TIMER_DELAYED
,
40 struct devfreq_governor
;
43 * struct devfreq_dev_status - Data given from devfreq user device to
44 * governors. Represents the performance
46 * @total_time: The total time represented by this instance of
48 * @busy_time: The time that the device was working among the
50 * @current_frequency: The operating frequency.
51 * @private_data: An entry not specified by the devfreq framework.
52 * A device and a specific governor may have their
53 * own protocol with private_data. However, because
54 * this is governor-specific, a governor using this
55 * will be only compatible with devices aware of it.
57 struct devfreq_dev_status
{
58 /* both since the last measure */
59 unsigned long total_time
;
60 unsigned long busy_time
;
61 unsigned long current_frequency
;
66 * The resulting frequency should be at most this. (this bound is the
67 * least upper bound; thus, the resulting freq should be lower or same)
68 * If the flag is not set, the resulting frequency should be at most the
69 * bound (greatest lower bound)
71 #define DEVFREQ_FLAG_LEAST_UPPER_BOUND 0x1
74 * struct devfreq_dev_profile - Devfreq's user device profile
75 * @initial_freq: The operating frequency when devfreq_add_device() is
77 * @polling_ms: The polling interval in ms. 0 disables polling.
78 * @timer: Timer type is either deferrable or delayed timer.
79 * @target: The device should set its operating frequency at
80 * freq or lowest-upper-than-freq value. If freq is
81 * higher than any operable frequency, set maximum.
82 * Before returning, target function should set
83 * freq at the current frequency.
84 * The "flags" parameter's possible values are
85 * explained above with "DEVFREQ_FLAG_*" macros.
86 * @get_dev_status: The device should provide the current performance
87 * status to devfreq. Governors are recommended not to
88 * use this directly. Instead, governors are recommended
89 * to use devfreq_update_stats() along with
90 * devfreq.last_status.
91 * @get_cur_freq: The device should provide the current frequency
92 * at which it is operating.
93 * @exit: An optional callback that is called when devfreq
94 * is removing the devfreq object due to error or
95 * from devfreq_remove_device() call. If the user
96 * has registered devfreq->nb at a notifier-head,
97 * this is the time to unregister it.
98 * @freq_table: Optional list of frequencies to support statistics
99 * and freq_table must be generated in ascending order.
100 * @max_state: The size of freq_table.
102 struct devfreq_dev_profile
{
103 unsigned long initial_freq
;
104 unsigned int polling_ms
;
105 enum devfreq_timer timer
;
107 int (*target
)(struct device
*dev
, unsigned long *freq
, u32 flags
);
108 int (*get_dev_status
)(struct device
*dev
,
109 struct devfreq_dev_status
*stat
);
110 int (*get_cur_freq
)(struct device
*dev
, unsigned long *freq
);
111 void (*exit
)(struct device
*dev
);
113 unsigned long *freq_table
;
114 unsigned int max_state
;
118 * struct devfreq_stats - Statistics of devfreq device behavior
119 * @total_trans: Number of devfreq transitions.
120 * @trans_table: Statistics of devfreq transitions.
121 * @time_in_state: Statistics of devfreq states.
122 * @last_update: The last time stats were updated.
124 struct devfreq_stats
{
125 unsigned int total_trans
;
126 unsigned int *trans_table
;
132 * struct devfreq - Device devfreq structure
133 * @node: list node - contains the devices with devfreq that have been
135 * @lock: a mutex to protect accessing devfreq.
136 * @dev: device registered by devfreq class. dev.parent is the device
138 * @profile: device-specific devfreq profile
139 * @governor: method how to choose frequency based on the usage.
140 * @nb: notifier block used to notify devfreq object that it should
141 * reevaluate operable frequencies. Devfreq users may use
142 * devfreq.nb to the corresponding register notifier call chain.
143 * @work: delayed work for load monitoring.
144 * @previous_freq: previously configured frequency value.
145 * @last_status: devfreq user device info, performance statistics
146 * @data: Private data of the governor. The devfreq framework does not
148 * @user_min_freq_req: PM QoS minimum frequency request from user (via sysfs)
149 * @user_max_freq_req: PM QoS maximum frequency request from user (via sysfs)
150 * @scaling_min_freq: Limit minimum frequency requested by OPP interface
151 * @scaling_max_freq: Limit maximum frequency requested by OPP interface
152 * @stop_polling: devfreq polling status of a device.
153 * @suspend_freq: frequency of a device set during suspend phase.
154 * @resume_freq: frequency of a device set in resume phase.
155 * @suspend_count: suspend requests counter for a device.
156 * @stats: Statistics of devfreq device behavior
157 * @transition_notifier_list: list head of DEVFREQ_TRANSITION_NOTIFIER notifier
158 * @nb_min: Notifier block for DEV_PM_QOS_MIN_FREQUENCY
159 * @nb_max: Notifier block for DEV_PM_QOS_MAX_FREQUENCY
161 * This structure stores the devfreq information for a given device.
163 * Note that when a governor accesses entries in struct devfreq in its
164 * functions except for the context of callbacks defined in struct
165 * devfreq_governor, the governor should protect its access with the
166 * struct mutex lock in struct devfreq. A governor may use this mutex
167 * to protect its own private data in ``void *data`` as well.
170 struct list_head node
;
174 struct devfreq_dev_profile
*profile
;
175 const struct devfreq_governor
*governor
;
176 struct notifier_block nb
;
177 struct delayed_work work
;
179 unsigned long previous_freq
;
180 struct devfreq_dev_status last_status
;
182 void *data
; /* private data for governors */
184 struct dev_pm_qos_request user_min_freq_req
;
185 struct dev_pm_qos_request user_max_freq_req
;
186 unsigned long scaling_min_freq
;
187 unsigned long scaling_max_freq
;
190 unsigned long suspend_freq
;
191 unsigned long resume_freq
;
192 atomic_t suspend_count
;
194 /* information for device frequency transitions */
195 struct devfreq_stats stats
;
197 struct srcu_notifier_head transition_notifier_list
;
199 struct notifier_block nb_min
;
200 struct notifier_block nb_max
;
203 struct devfreq_freqs
{
208 #if defined(CONFIG_PM_DEVFREQ)
209 struct devfreq
*devfreq_add_device(struct device
*dev
,
210 struct devfreq_dev_profile
*profile
,
211 const char *governor_name
,
213 int devfreq_remove_device(struct devfreq
*devfreq
);
214 struct devfreq
*devm_devfreq_add_device(struct device
*dev
,
215 struct devfreq_dev_profile
*profile
,
216 const char *governor_name
,
218 void devm_devfreq_remove_device(struct device
*dev
, struct devfreq
*devfreq
);
220 /* Supposed to be called by PM callbacks */
221 int devfreq_suspend_device(struct devfreq
*devfreq
);
222 int devfreq_resume_device(struct devfreq
*devfreq
);
224 void devfreq_suspend(void);
225 void devfreq_resume(void);
227 /* update_devfreq() - Reevaluate the device and configure frequency */
228 int update_devfreq(struct devfreq
*devfreq
);
230 /* Helper functions for devfreq user device driver with OPP. */
231 struct dev_pm_opp
*devfreq_recommended_opp(struct device
*dev
,
232 unsigned long *freq
, u32 flags
);
233 int devfreq_register_opp_notifier(struct device
*dev
,
234 struct devfreq
*devfreq
);
235 int devfreq_unregister_opp_notifier(struct device
*dev
,
236 struct devfreq
*devfreq
);
237 int devm_devfreq_register_opp_notifier(struct device
*dev
,
238 struct devfreq
*devfreq
);
239 void devm_devfreq_unregister_opp_notifier(struct device
*dev
,
240 struct devfreq
*devfreq
);
241 int devfreq_register_notifier(struct devfreq
*devfreq
,
242 struct notifier_block
*nb
,
244 int devfreq_unregister_notifier(struct devfreq
*devfreq
,
245 struct notifier_block
*nb
,
247 int devm_devfreq_register_notifier(struct device
*dev
,
248 struct devfreq
*devfreq
,
249 struct notifier_block
*nb
,
251 void devm_devfreq_unregister_notifier(struct device
*dev
,
252 struct devfreq
*devfreq
,
253 struct notifier_block
*nb
,
255 struct devfreq
*devfreq_get_devfreq_by_node(struct device_node
*node
);
256 struct devfreq
*devfreq_get_devfreq_by_phandle(struct device
*dev
,
257 const char *phandle_name
, int index
);
259 #if IS_ENABLED(CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND)
261 * struct devfreq_simple_ondemand_data - ``void *data`` fed to struct devfreq
262 * and devfreq_add_device
263 * @upthreshold: If the load is over this value, the frequency jumps.
264 * Specify 0 to use the default. Valid value = 0 to 100.
265 * @downdifferential: If the load is under upthreshold - downdifferential,
266 * the governor may consider slowing the frequency down.
267 * Specify 0 to use the default. Valid value = 0 to 100.
268 * downdifferential < upthreshold must hold.
270 * If the fed devfreq_simple_ondemand_data pointer is NULL to the governor,
271 * the governor uses the default values.
273 struct devfreq_simple_ondemand_data
{
274 unsigned int upthreshold
;
275 unsigned int downdifferential
;
279 #if IS_ENABLED(CONFIG_DEVFREQ_GOV_PASSIVE)
281 * struct devfreq_passive_data - ``void *data`` fed to struct devfreq
282 * and devfreq_add_device
283 * @parent: the devfreq instance of parent device.
284 * @get_target_freq: Optional callback, Returns desired operating frequency
285 * for the device using passive governor. That is called
286 * when passive governor should decide the next frequency
287 * by using the new frequency of parent devfreq device
288 * using governors except for passive governor.
289 * If the devfreq device has the specific method to decide
290 * the next frequency, should use this callback.
291 * @this: the devfreq instance of own device.
292 * @nb: the notifier block for DEVFREQ_TRANSITION_NOTIFIER list
294 * The devfreq_passive_data have to set the devfreq instance of parent
295 * device with governors except for the passive governor. But, don't need to
296 * initialize the 'this' and 'nb' field because the devfreq core will handle
299 struct devfreq_passive_data
{
300 /* Should set the devfreq instance of parent device */
301 struct devfreq
*parent
;
303 /* Optional callback to decide the next frequency of passvice device */
304 int (*get_target_freq
)(struct devfreq
*this, unsigned long *freq
);
306 /* For passive governor's internal use. Don't need to set them */
307 struct devfreq
*this;
308 struct notifier_block nb
;
312 #else /* !CONFIG_PM_DEVFREQ */
313 static inline struct devfreq
*devfreq_add_device(struct device
*dev
,
314 struct devfreq_dev_profile
*profile
,
315 const char *governor_name
,
318 return ERR_PTR(-ENOSYS
);
321 static inline int devfreq_remove_device(struct devfreq
*devfreq
)
326 static inline struct devfreq
*devm_devfreq_add_device(struct device
*dev
,
327 struct devfreq_dev_profile
*profile
,
328 const char *governor_name
,
331 return ERR_PTR(-ENOSYS
);
334 static inline void devm_devfreq_remove_device(struct device
*dev
,
335 struct devfreq
*devfreq
)
339 static inline int devfreq_suspend_device(struct devfreq
*devfreq
)
344 static inline int devfreq_resume_device(struct devfreq
*devfreq
)
349 static inline void devfreq_suspend(void) {}
350 static inline void devfreq_resume(void) {}
352 static inline struct dev_pm_opp
*devfreq_recommended_opp(struct device
*dev
,
353 unsigned long *freq
, u32 flags
)
355 return ERR_PTR(-EINVAL
);
358 static inline int devfreq_register_opp_notifier(struct device
*dev
,
359 struct devfreq
*devfreq
)
364 static inline int devfreq_unregister_opp_notifier(struct device
*dev
,
365 struct devfreq
*devfreq
)
370 static inline int devm_devfreq_register_opp_notifier(struct device
*dev
,
371 struct devfreq
*devfreq
)
376 static inline void devm_devfreq_unregister_opp_notifier(struct device
*dev
,
377 struct devfreq
*devfreq
)
381 static inline int devfreq_register_notifier(struct devfreq
*devfreq
,
382 struct notifier_block
*nb
,
388 static inline int devfreq_unregister_notifier(struct devfreq
*devfreq
,
389 struct notifier_block
*nb
,
395 static inline int devm_devfreq_register_notifier(struct device
*dev
,
396 struct devfreq
*devfreq
,
397 struct notifier_block
*nb
,
403 static inline void devm_devfreq_unregister_notifier(struct device
*dev
,
404 struct devfreq
*devfreq
,
405 struct notifier_block
*nb
,
410 static inline struct devfreq
*devfreq_get_devfreq_by_node(struct device_node
*node
)
412 return ERR_PTR(-ENODEV
);
415 static inline struct devfreq
*devfreq_get_devfreq_by_phandle(struct device
*dev
,
416 const char *phandle_name
, int index
)
418 return ERR_PTR(-ENODEV
);
421 static inline int devfreq_update_stats(struct devfreq
*df
)
425 #endif /* CONFIG_PM_DEVFREQ */
427 #endif /* __LINUX_DEVFREQ_H__ */