xref: /linux/include/linux/devfreq.h (revision fcc8487d477a3452a1d0ccbdd4c5e0e1e3cb8bed)
1 /*
2  * devfreq: Generic Dynamic Voltage and Frequency Scaling (DVFS) Framework
3  *	    for Non-CPU Devices.
4  *
5  * Copyright (C) 2011 Samsung Electronics
6  *	MyungJoo Ham <myungjoo.ham@samsung.com>
7  *
8  * This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License version 2 as
10  * published by the Free Software Foundation.
11  */
12 
13 #ifndef __LINUX_DEVFREQ_H__
14 #define __LINUX_DEVFREQ_H__
15 
16 #include <linux/device.h>
17 #include <linux/notifier.h>
18 #include <linux/pm_opp.h>
19 
20 #define DEVFREQ_NAME_LEN 16
21 
22 /* DEVFREQ notifier interface */
23 #define DEVFREQ_TRANSITION_NOTIFIER	(0)
24 
25 /* Transition notifiers of DEVFREQ_TRANSITION_NOTIFIER */
26 #define	DEVFREQ_PRECHANGE		(0)
27 #define DEVFREQ_POSTCHANGE		(1)
28 
29 struct devfreq;
30 struct devfreq_governor;
31 
32 /**
33  * struct devfreq_dev_status - Data given from devfreq user device to
34  *			     governors. Represents the performance
35  *			     statistics.
36  * @total_time:		The total time represented by this instance of
37  *			devfreq_dev_status
38  * @busy_time:		The time that the device was working among the
39  *			total_time.
40  * @current_frequency:	The operating frequency.
41  * @private_data:	An entry not specified by the devfreq framework.
42  *			A device and a specific governor may have their
43  *			own protocol with private_data. However, because
44  *			this is governor-specific, a governor using this
45  *			will be only compatible with devices aware of it.
46  */
47 struct devfreq_dev_status {
48 	/* both since the last measure */
49 	unsigned long total_time;
50 	unsigned long busy_time;
51 	unsigned long current_frequency;
52 	void *private_data;
53 };
54 
55 /*
56  * The resulting frequency should be at most this. (this bound is the
57  * least upper bound; thus, the resulting freq should be lower or same)
58  * If the flag is not set, the resulting frequency should be at most the
59  * bound (greatest lower bound)
60  */
61 #define DEVFREQ_FLAG_LEAST_UPPER_BOUND		0x1
62 
63 /**
64  * struct devfreq_dev_profile - Devfreq's user device profile
65  * @initial_freq:	The operating frequency when devfreq_add_device() is
66  *			called.
67  * @polling_ms:		The polling interval in ms. 0 disables polling.
68  * @target:		The device should set its operating frequency at
69  *			freq or lowest-upper-than-freq value. If freq is
70  *			higher than any operable frequency, set maximum.
71  *			Before returning, target function should set
72  *			freq at the current frequency.
73  *			The "flags" parameter's possible values are
74  *			explained above with "DEVFREQ_FLAG_*" macros.
75  * @get_dev_status:	The device should provide the current performance
76  *			status to devfreq. Governors are recommended not to
77  *			use this directly. Instead, governors are recommended
78  *			to use devfreq_update_stats() along with
79  *			devfreq.last_status.
80  * @get_cur_freq:	The device should provide the current frequency
81  *			at which it is operating.
82  * @exit:		An optional callback that is called when devfreq
83  *			is removing the devfreq object due to error or
84  *			from devfreq_remove_device() call. If the user
85  *			has registered devfreq->nb at a notifier-head,
86  *			this is the time to unregister it.
87  * @freq_table:	Optional list of frequencies to support statistics.
88  * @max_state:	The size of freq_table.
89  */
90 struct devfreq_dev_profile {
91 	unsigned long initial_freq;
92 	unsigned int polling_ms;
93 
94 	int (*target)(struct device *dev, unsigned long *freq, u32 flags);
95 	int (*get_dev_status)(struct device *dev,
96 			      struct devfreq_dev_status *stat);
97 	int (*get_cur_freq)(struct device *dev, unsigned long *freq);
98 	void (*exit)(struct device *dev);
99 
100 	unsigned long *freq_table;
101 	unsigned int max_state;
102 };
103 
104 /**
105  * struct devfreq - Device devfreq structure
106  * @node:	list node - contains the devices with devfreq that have been
107  *		registered.
108  * @lock:	a mutex to protect accessing devfreq.
109  * @dev:	device registered by devfreq class. dev.parent is the device
110  *		using devfreq.
111  * @profile:	device-specific devfreq profile
112  * @governor:	method how to choose frequency based on the usage.
113  * @governor_name:	devfreq governor name for use with this devfreq
114  * @nb:		notifier block used to notify devfreq object that it should
115  *		reevaluate operable frequencies. Devfreq users may use
116  *		devfreq.nb to the corresponding register notifier call chain.
117  * @work:	delayed work for load monitoring.
118  * @previous_freq:	previously configured frequency value.
119  * @data:	Private data of the governor. The devfreq framework does not
120  *		touch this.
121  * @min_freq:	Limit minimum frequency requested by user (0: none)
122  * @max_freq:	Limit maximum frequency requested by user (0: none)
123  * @stop_polling:	 devfreq polling status of a device.
124  * @total_trans:	Number of devfreq transitions
125  * @trans_table:	Statistics of devfreq transitions
126  * @time_in_state:	Statistics of devfreq states
127  * @last_stat_updated:	The last time stat updated
128  * @transition_notifier_list: list head of DEVFREQ_TRANSITION_NOTIFIER notifier
129  *
130  * This structure stores the devfreq information for a give device.
131  *
132  * Note that when a governor accesses entries in struct devfreq in its
133  * functions except for the context of callbacks defined in struct
134  * devfreq_governor, the governor should protect its access with the
135  * struct mutex lock in struct devfreq. A governor may use this mutex
136  * to protect its own private data in void *data as well.
137  */
138 struct devfreq {
139 	struct list_head node;
140 
141 	struct mutex lock;
142 	struct device dev;
143 	struct devfreq_dev_profile *profile;
144 	const struct devfreq_governor *governor;
145 	char governor_name[DEVFREQ_NAME_LEN];
146 	struct notifier_block nb;
147 	struct delayed_work work;
148 
149 	unsigned long previous_freq;
150 	struct devfreq_dev_status last_status;
151 
152 	void *data; /* private data for governors */
153 
154 	unsigned long min_freq;
155 	unsigned long max_freq;
156 	bool stop_polling;
157 
158 	/* information for device frequency transition */
159 	unsigned int total_trans;
160 	unsigned int *trans_table;
161 	unsigned long *time_in_state;
162 	unsigned long last_stat_updated;
163 
164 	struct srcu_notifier_head transition_notifier_list;
165 };
166 
167 struct devfreq_freqs {
168 	unsigned long old;
169 	unsigned long new;
170 };
171 
172 #if defined(CONFIG_PM_DEVFREQ)
173 extern struct devfreq *devfreq_add_device(struct device *dev,
174 				  struct devfreq_dev_profile *profile,
175 				  const char *governor_name,
176 				  void *data);
177 extern int devfreq_remove_device(struct devfreq *devfreq);
178 extern struct devfreq *devm_devfreq_add_device(struct device *dev,
179 				  struct devfreq_dev_profile *profile,
180 				  const char *governor_name,
181 				  void *data);
182 extern void devm_devfreq_remove_device(struct device *dev,
183 				  struct devfreq *devfreq);
184 
185 /* Supposed to be called by PM callbacks */
186 extern int devfreq_suspend_device(struct devfreq *devfreq);
187 extern int devfreq_resume_device(struct devfreq *devfreq);
188 
189 /* Helper functions for devfreq user device driver with OPP. */
190 extern struct dev_pm_opp *devfreq_recommended_opp(struct device *dev,
191 					   unsigned long *freq, u32 flags);
192 extern int devfreq_register_opp_notifier(struct device *dev,
193 					 struct devfreq *devfreq);
194 extern int devfreq_unregister_opp_notifier(struct device *dev,
195 					   struct devfreq *devfreq);
196 extern int devm_devfreq_register_opp_notifier(struct device *dev,
197 					      struct devfreq *devfreq);
198 extern void devm_devfreq_unregister_opp_notifier(struct device *dev,
199 						struct devfreq *devfreq);
200 extern int devfreq_register_notifier(struct devfreq *devfreq,
201 					struct notifier_block *nb,
202 					unsigned int list);
203 extern int devfreq_unregister_notifier(struct devfreq *devfreq,
204 					struct notifier_block *nb,
205 					unsigned int list);
206 extern int devm_devfreq_register_notifier(struct device *dev,
207 				struct devfreq *devfreq,
208 				struct notifier_block *nb,
209 				unsigned int list);
210 extern void devm_devfreq_unregister_notifier(struct device *dev,
211 				struct devfreq *devfreq,
212 				struct notifier_block *nb,
213 				unsigned int list);
214 extern struct devfreq *devfreq_get_devfreq_by_phandle(struct device *dev,
215 						int index);
216 
217 /**
218  * devfreq_update_stats() - update the last_status pointer in struct devfreq
219  * @df:		the devfreq instance whose status needs updating
220  *
221  *  Governors are recommended to use this function along with last_status,
222  * which allows other entities to reuse the last_status without affecting
223  * the values fetched later by governors.
224  */
225 static inline int devfreq_update_stats(struct devfreq *df)
226 {
227 	return df->profile->get_dev_status(df->dev.parent, &df->last_status);
228 }
229 
230 #if IS_ENABLED(CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND)
231 /**
232  * struct devfreq_simple_ondemand_data - void *data fed to struct devfreq
233  *	and devfreq_add_device
234  * @upthreshold:	If the load is over this value, the frequency jumps.
235  *			Specify 0 to use the default. Valid value = 0 to 100.
236  * @downdifferential:	If the load is under upthreshold - downdifferential,
237  *			the governor may consider slowing the frequency down.
238  *			Specify 0 to use the default. Valid value = 0 to 100.
239  *			downdifferential < upthreshold must hold.
240  *
241  * If the fed devfreq_simple_ondemand_data pointer is NULL to the governor,
242  * the governor uses the default values.
243  */
244 struct devfreq_simple_ondemand_data {
245 	unsigned int upthreshold;
246 	unsigned int downdifferential;
247 };
248 #endif
249 
250 #if IS_ENABLED(CONFIG_DEVFREQ_GOV_PASSIVE)
251 /**
252  * struct devfreq_passive_data - void *data fed to struct devfreq
253  *	and devfreq_add_device
254  * @parent:	the devfreq instance of parent device.
255  * @get_target_freq:	Optional callback, Returns desired operating frequency
256  *			for the device using passive governor. That is called
257  *			when passive governor should decide the next frequency
258  *			by using the new frequency of parent devfreq device
259  *			using governors except for passive governor.
260  *			If the devfreq device has the specific method to decide
261  *			the next frequency, should use this callback.
262  * @this:	the devfreq instance of own device.
263  * @nb:		the notifier block for DEVFREQ_TRANSITION_NOTIFIER list
264  *
265  * The devfreq_passive_data have to set the devfreq instance of parent
266  * device with governors except for the passive governor. But, don't need to
267  * initialize the 'this' and 'nb' field because the devfreq core will handle
268  * them.
269  */
270 struct devfreq_passive_data {
271 	/* Should set the devfreq instance of parent device */
272 	struct devfreq *parent;
273 
274 	/* Optional callback to decide the next frequency of passvice device */
275 	int (*get_target_freq)(struct devfreq *this, unsigned long *freq);
276 
277 	/* For passive governor's internal use. Don't need to set them */
278 	struct devfreq *this;
279 	struct notifier_block nb;
280 };
281 #endif
282 
283 #else /* !CONFIG_PM_DEVFREQ */
284 static inline struct devfreq *devfreq_add_device(struct device *dev,
285 					  struct devfreq_dev_profile *profile,
286 					  const char *governor_name,
287 					  void *data)
288 {
289 	return ERR_PTR(-ENOSYS);
290 }
291 
292 static inline int devfreq_remove_device(struct devfreq *devfreq)
293 {
294 	return 0;
295 }
296 
297 static inline struct devfreq *devm_devfreq_add_device(struct device *dev,
298 					struct devfreq_dev_profile *profile,
299 					const char *governor_name,
300 					void *data)
301 {
302 	return ERR_PTR(-ENOSYS);
303 }
304 
305 static inline void devm_devfreq_remove_device(struct device *dev,
306 					struct devfreq *devfreq)
307 {
308 }
309 
310 static inline int devfreq_suspend_device(struct devfreq *devfreq)
311 {
312 	return 0;
313 }
314 
315 static inline int devfreq_resume_device(struct devfreq *devfreq)
316 {
317 	return 0;
318 }
319 
320 static inline struct dev_pm_opp *devfreq_recommended_opp(struct device *dev,
321 					   unsigned long *freq, u32 flags)
322 {
323 	return ERR_PTR(-EINVAL);
324 }
325 
326 static inline int devfreq_register_opp_notifier(struct device *dev,
327 					 struct devfreq *devfreq)
328 {
329 	return -EINVAL;
330 }
331 
332 static inline int devfreq_unregister_opp_notifier(struct device *dev,
333 					   struct devfreq *devfreq)
334 {
335 	return -EINVAL;
336 }
337 
338 static inline int devm_devfreq_register_opp_notifier(struct device *dev,
339 						     struct devfreq *devfreq)
340 {
341 	return -EINVAL;
342 }
343 
344 static inline void devm_devfreq_unregister_opp_notifier(struct device *dev,
345 							struct devfreq *devfreq)
346 {
347 }
348 
349 static inline int devfreq_register_notifier(struct devfreq *devfreq,
350 					struct notifier_block *nb,
351 					unsigned int list)
352 {
353 	return 0;
354 }
355 
356 static inline int devfreq_unregister_notifier(struct devfreq *devfreq,
357 					struct notifier_block *nb,
358 					unsigned int list)
359 {
360 	return 0;
361 }
362 
363 static inline int devm_devfreq_register_notifier(struct device *dev,
364 				struct devfreq *devfreq,
365 				struct notifier_block *nb,
366 				unsigned int list)
367 {
368 	return 0;
369 }
370 
371 static inline void devm_devfreq_unregister_notifier(struct device *dev,
372 				struct devfreq *devfreq,
373 				struct notifier_block *nb,
374 				unsigned int list)
375 {
376 }
377 
378 static inline struct devfreq *devfreq_get_devfreq_by_phandle(struct device *dev,
379 							int index)
380 {
381 	return ERR_PTR(-ENODEV);
382 }
383 
384 static inline int devfreq_update_stats(struct devfreq *df)
385 {
386 	return -EINVAL;
387 }
388 #endif /* CONFIG_PM_DEVFREQ */
389 
390 #endif /* __LINUX_DEVFREQ_H__ */
391