thermal.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * thermal.h ($Revision: 0 $)
  4. *
  5. * Copyright (C) 2008 Intel Corp
  6. * Copyright (C) 2008 Zhang Rui <[email protected]>
  7. * Copyright (C) 2008 Sujith Thomas <[email protected]>
  8. */
  9. #ifndef __THERMAL_H__
  10. #define __THERMAL_H__
  11. #include <linux/of.h>
  12. #include <linux/idr.h>
  13. #include <linux/device.h>
  14. #include <linux/sysfs.h>
  15. #include <linux/workqueue.h>
  16. #include <linux/android_kabi.h>
  17. #include <uapi/linux/thermal.h>
  18. /* invalid cooling state */
  19. #define THERMAL_CSTATE_INVALID -1UL
  20. /* No upper/lower limit requirement */
  21. #define THERMAL_NO_LIMIT ((u32)~0)
  22. /* Default weight of a bound cooling device */
  23. #define THERMAL_WEIGHT_DEFAULT 0
  24. /* use value, which < 0K, to indicate an invalid/uninitialized temperature */
  25. #define THERMAL_TEMP_INVALID -274000
  26. struct thermal_zone_device;
  27. struct thermal_cooling_device;
  28. struct thermal_instance;
  29. struct thermal_attr;
  30. enum thermal_trend {
  31. THERMAL_TREND_STABLE, /* temperature is stable */
  32. THERMAL_TREND_RAISING, /* temperature is raising */
  33. THERMAL_TREND_DROPPING, /* temperature is dropping */
  34. };
  35. /* Thermal notification reason */
  36. enum thermal_notify_event {
  37. THERMAL_EVENT_UNSPECIFIED, /* Unspecified event */
  38. THERMAL_EVENT_TEMP_SAMPLE, /* New Temperature sample */
  39. THERMAL_TRIP_VIOLATED, /* TRIP Point violation */
  40. THERMAL_TRIP_CHANGED, /* TRIP Point temperature changed */
  41. THERMAL_DEVICE_DOWN, /* Thermal device is down */
  42. THERMAL_DEVICE_UP, /* Thermal device is up after a down event */
  43. THERMAL_DEVICE_POWER_CAPABILITY_CHANGED, /* power capability changed */
  44. THERMAL_TABLE_CHANGED, /* Thermal table(s) changed */
  45. THERMAL_EVENT_KEEP_ALIVE, /* Request for user space handler to respond */
  46. };
  47. struct thermal_zone_device_ops {
  48. int (*bind) (struct thermal_zone_device *,
  49. struct thermal_cooling_device *);
  50. int (*unbind) (struct thermal_zone_device *,
  51. struct thermal_cooling_device *);
  52. int (*get_temp) (struct thermal_zone_device *, int *);
  53. int (*set_trips) (struct thermal_zone_device *, int, int);
  54. int (*change_mode) (struct thermal_zone_device *,
  55. enum thermal_device_mode);
  56. int (*get_trip_type) (struct thermal_zone_device *, int,
  57. enum thermal_trip_type *);
  58. int (*get_trip_temp) (struct thermal_zone_device *, int, int *);
  59. int (*set_trip_temp) (struct thermal_zone_device *, int, int);
  60. int (*get_trip_hyst) (struct thermal_zone_device *, int, int *);
  61. int (*set_trip_hyst) (struct thermal_zone_device *, int, int);
  62. int (*get_crit_temp) (struct thermal_zone_device *, int *);
  63. int (*set_emul_temp) (struct thermal_zone_device *, int);
  64. int (*get_trend) (struct thermal_zone_device *, int,
  65. enum thermal_trend *);
  66. void (*hot)(struct thermal_zone_device *);
  67. void (*critical)(struct thermal_zone_device *);
  68. ANDROID_KABI_RESERVE(1);
  69. };
  70. /**
  71. * struct thermal_trip - representation of a point in temperature domain
  72. * @temperature: temperature value in miliCelsius
  73. * @hysteresis: relative hysteresis in miliCelsius
  74. * @type: trip point type
  75. */
  76. struct thermal_trip {
  77. int temperature;
  78. int hysteresis;
  79. enum thermal_trip_type type;
  80. };
  81. struct thermal_cooling_device_ops {
  82. int (*get_max_state) (struct thermal_cooling_device *, unsigned long *);
  83. int (*get_cur_state) (struct thermal_cooling_device *, unsigned long *);
  84. int (*set_cur_state) (struct thermal_cooling_device *, unsigned long);
  85. int (*get_requested_power)(struct thermal_cooling_device *, u32 *);
  86. int (*state2power)(struct thermal_cooling_device *, unsigned long, u32 *);
  87. int (*power2state)(struct thermal_cooling_device *, u32, unsigned long *);
  88. ANDROID_KABI_RESERVE(1);
  89. };
  90. struct thermal_cooling_device {
  91. int id;
  92. char *type;
  93. unsigned long max_state;
  94. struct device device;
  95. struct device_node *np;
  96. void *devdata;
  97. void *stats;
  98. const struct thermal_cooling_device_ops *ops;
  99. bool updated; /* true if the cooling device does not need update */
  100. struct mutex lock; /* protect thermal_instances list */
  101. struct list_head thermal_instances;
  102. struct list_head node;
  103. ANDROID_KABI_RESERVE(1);
  104. };
  105. /**
  106. * struct thermal_zone_device - structure for a thermal zone
  107. * @id: unique id number for each thermal zone
  108. * @type: the thermal zone device type
  109. * @device: &struct device for this thermal zone
  110. * @trip_temp_attrs: attributes for trip points for sysfs: trip temperature
  111. * @trip_type_attrs: attributes for trip points for sysfs: trip type
  112. * @trip_hyst_attrs: attributes for trip points for sysfs: trip hysteresis
  113. * @mode: current mode of this thermal zone
  114. * @devdata: private pointer for device private data
  115. * @trips: an array of struct thermal_trip
  116. * @num_trips: number of trip points the thermal zone supports
  117. * @trips_disabled; bitmap for disabled trips
  118. * @passive_delay_jiffies: number of jiffies to wait between polls when
  119. * performing passive cooling.
  120. * @polling_delay_jiffies: number of jiffies to wait between polls when
  121. * checking whether trip points have been crossed (0 for
  122. * interrupt driven systems)
  123. * @temperature: current temperature. This is only for core code,
  124. * drivers should use thermal_zone_get_temp() to get the
  125. * current temperature
  126. * @last_temperature: previous temperature read
  127. * @emul_temperature: emulated temperature when using CONFIG_THERMAL_EMULATION
  128. * @passive: 1 if you've crossed a passive trip point, 0 otherwise.
  129. * @prev_low_trip: the low current temperature if you've crossed a passive
  130. trip point.
  131. * @prev_high_trip: the above current temperature if you've crossed a
  132. passive trip point.
  133. * @need_update: if equals 1, thermal_zone_device_update needs to be invoked.
  134. * @ops: operations this &thermal_zone_device supports
  135. * @tzp: thermal zone parameters
  136. * @governor: pointer to the governor for this thermal zone
  137. * @governor_data: private pointer for governor data
  138. * @thermal_instances: list of &struct thermal_instance of this thermal zone
  139. * @ida: &struct ida to generate unique id for this zone's cooling
  140. * devices
  141. * @lock: lock to protect thermal_instances list
  142. * @node: node in thermal_tz_list (in thermal_core.c)
  143. * @poll_queue: delayed work for polling
  144. * @notify_event: Last notification event
  145. */
  146. struct thermal_zone_device {
  147. int id;
  148. char type[THERMAL_NAME_LENGTH];
  149. struct device device;
  150. struct attribute_group trips_attribute_group;
  151. struct thermal_attr *trip_temp_attrs;
  152. struct thermal_attr *trip_type_attrs;
  153. struct thermal_attr *trip_hyst_attrs;
  154. enum thermal_device_mode mode;
  155. void *devdata;
  156. struct thermal_trip *trips;
  157. int num_trips;
  158. unsigned long trips_disabled; /* bitmap for disabled trips */
  159. unsigned long passive_delay_jiffies;
  160. unsigned long polling_delay_jiffies;
  161. int temperature;
  162. int last_temperature;
  163. int emul_temperature;
  164. int passive;
  165. int prev_low_trip;
  166. int prev_high_trip;
  167. atomic_t need_update;
  168. struct thermal_zone_device_ops *ops;
  169. struct thermal_zone_params *tzp;
  170. struct thermal_governor *governor;
  171. void *governor_data;
  172. struct list_head thermal_instances;
  173. struct ida ida;
  174. struct mutex lock;
  175. struct list_head node;
  176. struct delayed_work poll_queue;
  177. enum thermal_notify_event notify_event;
  178. ANDROID_KABI_RESERVE(1);
  179. };
  180. /**
  181. * struct thermal_governor - structure that holds thermal governor information
  182. * @name: name of the governor
  183. * @bind_to_tz: callback called when binding to a thermal zone. If it
  184. * returns 0, the governor is bound to the thermal zone,
  185. * otherwise it fails.
  186. * @unbind_from_tz: callback called when a governor is unbound from a
  187. * thermal zone.
  188. * @throttle: callback called for every trip point even if temperature is
  189. * below the trip point temperature
  190. * @governor_list: node in thermal_governor_list (in thermal_core.c)
  191. */
  192. struct thermal_governor {
  193. char name[THERMAL_NAME_LENGTH];
  194. int (*bind_to_tz)(struct thermal_zone_device *tz);
  195. void (*unbind_from_tz)(struct thermal_zone_device *tz);
  196. int (*throttle)(struct thermal_zone_device *tz, int trip);
  197. struct list_head governor_list;
  198. ANDROID_KABI_RESERVE(1);
  199. };
  200. /* Structure that holds binding parameters for a zone */
  201. struct thermal_bind_params {
  202. struct thermal_cooling_device *cdev;
  203. /*
  204. * This is a measure of 'how effectively these devices can
  205. * cool 'this' thermal zone. It shall be determined by
  206. * platform characterization. This value is relative to the
  207. * rest of the weights so a cooling device whose weight is
  208. * double that of another cooling device is twice as
  209. * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
  210. * information.
  211. */
  212. int weight;
  213. /*
  214. * This is a bit mask that gives the binding relation between this
  215. * thermal zone and cdev, for a particular trip point.
  216. * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
  217. */
  218. int trip_mask;
  219. /*
  220. * This is an array of cooling state limits. Must have exactly
  221. * 2 * thermal_zone.number_of_trip_points. It is an array consisting
  222. * of tuples <lower-state upper-state> of state limits. Each trip
  223. * will be associated with one state limit tuple when binding.
  224. * A NULL pointer means <THERMAL_NO_LIMITS THERMAL_NO_LIMITS>
  225. * on all trips.
  226. */
  227. unsigned long *binding_limits;
  228. int (*match) (struct thermal_zone_device *tz,
  229. struct thermal_cooling_device *cdev);
  230. ANDROID_KABI_RESERVE(1);
  231. };
  232. /* Structure to define Thermal Zone parameters */
  233. struct thermal_zone_params {
  234. char governor_name[THERMAL_NAME_LENGTH];
  235. /*
  236. * a boolean to indicate if the thermal to hwmon sysfs interface
  237. * is required. when no_hwmon == false, a hwmon sysfs interface
  238. * will be created. when no_hwmon == true, nothing will be done
  239. */
  240. bool no_hwmon;
  241. int num_tbps; /* Number of tbp entries */
  242. struct thermal_bind_params *tbp;
  243. /*
  244. * Sustainable power (heat) that this thermal zone can dissipate in
  245. * mW
  246. */
  247. u32 sustainable_power;
  248. /*
  249. * Proportional parameter of the PID controller when
  250. * overshooting (i.e., when temperature is below the target)
  251. */
  252. s32 k_po;
  253. /*
  254. * Proportional parameter of the PID controller when
  255. * undershooting
  256. */
  257. s32 k_pu;
  258. /* Integral parameter of the PID controller */
  259. s32 k_i;
  260. /* Derivative parameter of the PID controller */
  261. s32 k_d;
  262. /* threshold below which the error is no longer accumulated */
  263. s32 integral_cutoff;
  264. /*
  265. * @slope: slope of a linear temperature adjustment curve.
  266. * Used by thermal zone drivers.
  267. */
  268. int slope;
  269. /*
  270. * @offset: offset of a linear temperature adjustment curve.
  271. * Used by thermal zone drivers (default 0).
  272. */
  273. int offset;
  274. ANDROID_KABI_RESERVE(1);
  275. };
  276. /* Function declarations */
  277. #ifdef CONFIG_THERMAL_OF
  278. struct thermal_zone_device *thermal_of_zone_register(struct device_node *sensor, int id, void *data,
  279. const struct thermal_zone_device_ops *ops);
  280. struct thermal_zone_device *devm_thermal_of_zone_register(struct device *dev, int id, void *data,
  281. const struct thermal_zone_device_ops *ops);
  282. void thermal_of_zone_unregister(struct thermal_zone_device *tz);
  283. void devm_thermal_of_zone_unregister(struct device *dev, struct thermal_zone_device *tz);
  284. void thermal_of_zone_unregister(struct thermal_zone_device *tz);
  285. #else
  286. static inline
  287. struct thermal_zone_device *thermal_of_zone_register(struct device_node *sensor, int id, void *data,
  288. const struct thermal_zone_device_ops *ops)
  289. {
  290. return ERR_PTR(-ENOTSUPP);
  291. }
  292. static inline
  293. struct thermal_zone_device *devm_thermal_of_zone_register(struct device *dev, int id, void *data,
  294. const struct thermal_zone_device_ops *ops)
  295. {
  296. return ERR_PTR(-ENOTSUPP);
  297. }
  298. static inline void thermal_of_zone_unregister(struct thermal_zone_device *tz)
  299. {
  300. }
  301. static inline void devm_thermal_of_zone_unregister(struct device *dev,
  302. struct thermal_zone_device *tz)
  303. {
  304. }
  305. #endif
  306. #ifdef CONFIG_THERMAL
  307. struct thermal_zone_device *thermal_zone_device_register(const char *, int, int,
  308. void *, struct thermal_zone_device_ops *,
  309. struct thermal_zone_params *, int, int);
  310. void thermal_zone_device_unregister(struct thermal_zone_device *);
  311. struct thermal_zone_device *
  312. thermal_zone_device_register_with_trips(const char *, struct thermal_trip *, int, int,
  313. void *, struct thermal_zone_device_ops *,
  314. struct thermal_zone_params *, int, int);
  315. int thermal_zone_bind_cooling_device(struct thermal_zone_device *, int,
  316. struct thermal_cooling_device *,
  317. unsigned long, unsigned long,
  318. unsigned int);
  319. int thermal_zone_unbind_cooling_device(struct thermal_zone_device *, int,
  320. struct thermal_cooling_device *);
  321. void thermal_zone_device_update(struct thermal_zone_device *,
  322. enum thermal_notify_event);
  323. struct thermal_cooling_device *thermal_cooling_device_register(const char *,
  324. void *, const struct thermal_cooling_device_ops *);
  325. struct thermal_cooling_device *
  326. thermal_of_cooling_device_register(struct device_node *np, const char *, void *,
  327. const struct thermal_cooling_device_ops *);
  328. struct thermal_cooling_device *
  329. devm_thermal_of_cooling_device_register(struct device *dev,
  330. struct device_node *np,
  331. char *type, void *devdata,
  332. const struct thermal_cooling_device_ops *ops);
  333. void thermal_cooling_device_unregister(struct thermal_cooling_device *);
  334. struct thermal_zone_device *thermal_zone_get_zone_by_name(const char *name);
  335. int thermal_zone_get_temp(struct thermal_zone_device *tz, int *temp);
  336. int thermal_zone_get_slope(struct thermal_zone_device *tz);
  337. int thermal_zone_get_offset(struct thermal_zone_device *tz);
  338. int thermal_zone_device_enable(struct thermal_zone_device *tz);
  339. int thermal_zone_device_disable(struct thermal_zone_device *tz);
  340. void thermal_zone_device_critical(struct thermal_zone_device *tz);
  341. #else
  342. static inline struct thermal_zone_device *thermal_zone_device_register(
  343. const char *type, int trips, int mask, void *devdata,
  344. struct thermal_zone_device_ops *ops,
  345. struct thermal_zone_params *tzp,
  346. int passive_delay, int polling_delay)
  347. { return ERR_PTR(-ENODEV); }
  348. static inline void thermal_zone_device_unregister(
  349. struct thermal_zone_device *tz)
  350. { }
  351. static inline struct thermal_cooling_device *
  352. thermal_cooling_device_register(const char *type, void *devdata,
  353. const struct thermal_cooling_device_ops *ops)
  354. { return ERR_PTR(-ENODEV); }
  355. static inline struct thermal_cooling_device *
  356. thermal_of_cooling_device_register(struct device_node *np,
  357. const char *type, void *devdata,
  358. const struct thermal_cooling_device_ops *ops)
  359. { return ERR_PTR(-ENODEV); }
  360. static inline struct thermal_cooling_device *
  361. devm_thermal_of_cooling_device_register(struct device *dev,
  362. struct device_node *np,
  363. char *type, void *devdata,
  364. const struct thermal_cooling_device_ops *ops)
  365. {
  366. return ERR_PTR(-ENODEV);
  367. }
  368. static inline void thermal_cooling_device_unregister(
  369. struct thermal_cooling_device *cdev)
  370. { }
  371. static inline struct thermal_zone_device *thermal_zone_get_zone_by_name(
  372. const char *name)
  373. { return ERR_PTR(-ENODEV); }
  374. static inline int thermal_zone_get_temp(
  375. struct thermal_zone_device *tz, int *temp)
  376. { return -ENODEV; }
  377. static inline int thermal_zone_get_slope(
  378. struct thermal_zone_device *tz)
  379. { return -ENODEV; }
  380. static inline int thermal_zone_get_offset(
  381. struct thermal_zone_device *tz)
  382. { return -ENODEV; }
  383. static inline int thermal_zone_device_enable(struct thermal_zone_device *tz)
  384. { return -ENODEV; }
  385. static inline int thermal_zone_device_disable(struct thermal_zone_device *tz)
  386. { return -ENODEV; }
  387. #endif /* CONFIG_THERMAL */
  388. #endif /* __THERMAL_H__ */