devfreq.h 15 KB

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