1 /*
2  *  thermal.h  ($Revision: 0 $)
3  *
4  *  Copyright (C) 2008  Intel Corp
5  *  Copyright (C) 2008  Zhang Rui <rui.zhang@intel.com>
6  *  Copyright (C) 2008  Sujith Thomas <sujith.thomas@intel.com>
7  *
8  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9  *  This program is free software; you can redistribute it and/or modify
10  *  it under the terms of the GNU General Public License as published by
11  *  the Free Software Foundation; version 2 of the License.
12  *
13  *  This program is distributed in the hope that it will be useful, but
14  *  WITHOUT ANY WARRANTY; without even the implied warranty of
15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  *  General Public License for more details.
17  *
18  *  You should have received a copy of the GNU General Public License along
19  *  with this program; if not, write to the Free Software Foundation, Inc.,
20  *  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
21  *
22  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23  */
24 
25 #ifndef __THERMAL_H__
26 #define __THERMAL_H__
27 
28 #include <linux/of.h>
29 #include <linux/idr.h>
30 #include <linux/device.h>
31 #include <linux/workqueue.h>
32 #include <uapi/linux/thermal.h>
33 
34 #define THERMAL_TRIPS_NONE	-1
35 #define THERMAL_MAX_TRIPS	12
36 
37 /* invalid cooling state */
38 #define THERMAL_CSTATE_INVALID -1UL
39 
40 /* No upper/lower limit requirement */
41 #define THERMAL_NO_LIMIT	((u32)~0)
42 
43 /* Default weight of a bound cooling device */
44 #define THERMAL_WEIGHT_DEFAULT 0
45 
46 /* use value, which < 0K, to indicate an invalid/uninitialized temperature */
47 #define THERMAL_TEMP_INVALID	-274000
48 
49 /* Unit conversion macros */
50 #define DECI_KELVIN_TO_CELSIUS(t)	({			\
51 	long _t = (t);						\
52 	((_t-2732 >= 0) ? (_t-2732+5)/10 : (_t-2732-5)/10);	\
53 })
54 #define CELSIUS_TO_DECI_KELVIN(t)	((t)*10+2732)
55 #define DECI_KELVIN_TO_MILLICELSIUS_WITH_OFFSET(t, off) (((t) - (off)) * 100)
56 #define DECI_KELVIN_TO_MILLICELSIUS(t) DECI_KELVIN_TO_MILLICELSIUS_WITH_OFFSET(t, 2732)
57 #define MILLICELSIUS_TO_DECI_KELVIN_WITH_OFFSET(t, off) (((t) / 100) + (off))
58 #define MILLICELSIUS_TO_DECI_KELVIN(t) MILLICELSIUS_TO_DECI_KELVIN_WITH_OFFSET(t, 2732)
59 
60 /* Default Thermal Governor */
61 #if defined(CONFIG_THERMAL_DEFAULT_GOV_STEP_WISE)
62 #define DEFAULT_THERMAL_GOVERNOR       "step_wise"
63 #elif defined(CONFIG_THERMAL_DEFAULT_GOV_FAIR_SHARE)
64 #define DEFAULT_THERMAL_GOVERNOR       "fair_share"
65 #elif defined(CONFIG_THERMAL_DEFAULT_GOV_USER_SPACE)
66 #define DEFAULT_THERMAL_GOVERNOR       "user_space"
67 #elif defined(CONFIG_THERMAL_DEFAULT_GOV_POWER_ALLOCATOR)
68 #define DEFAULT_THERMAL_GOVERNOR       "power_allocator"
69 #endif
70 
71 struct thermal_zone_device;
72 struct thermal_cooling_device;
73 struct thermal_instance;
74 
75 enum thermal_device_mode {
76 	THERMAL_DEVICE_DISABLED = 0,
77 	THERMAL_DEVICE_ENABLED,
78 };
79 
80 enum thermal_trip_type {
81 	THERMAL_TRIP_ACTIVE = 0,
82 	THERMAL_TRIP_PASSIVE,
83 	THERMAL_TRIP_HOT,
84 	THERMAL_TRIP_CRITICAL,
85 };
86 
87 enum thermal_trend {
88 	THERMAL_TREND_STABLE, /* temperature is stable */
89 	THERMAL_TREND_RAISING, /* temperature is raising */
90 	THERMAL_TREND_DROPPING, /* temperature is dropping */
91 	THERMAL_TREND_RAISE_FULL, /* apply highest cooling action */
92 	THERMAL_TREND_DROP_FULL, /* apply lowest cooling action */
93 };
94 
95 struct thermal_zone_device_ops {
96 	int (*bind) (struct thermal_zone_device *,
97 		     struct thermal_cooling_device *);
98 	int (*unbind) (struct thermal_zone_device *,
99 		       struct thermal_cooling_device *);
100 	int (*get_temp) (struct thermal_zone_device *, int *);
101 	int (*get_mode) (struct thermal_zone_device *,
102 			 enum thermal_device_mode *);
103 	int (*set_mode) (struct thermal_zone_device *,
104 		enum thermal_device_mode);
105 	int (*get_trip_type) (struct thermal_zone_device *, int,
106 		enum thermal_trip_type *);
107 	int (*get_trip_temp) (struct thermal_zone_device *, int, int *);
108 	int (*set_trip_temp) (struct thermal_zone_device *, int, int);
109 	int (*get_trip_hyst) (struct thermal_zone_device *, int, int *);
110 	int (*set_trip_hyst) (struct thermal_zone_device *, int, int);
111 	int (*get_crit_temp) (struct thermal_zone_device *, int *);
112 	int (*set_emul_temp) (struct thermal_zone_device *, int);
113 	int (*get_trend) (struct thermal_zone_device *, int,
114 			  enum thermal_trend *);
115 	int (*notify) (struct thermal_zone_device *, int,
116 		       enum thermal_trip_type);
117 };
118 
119 struct thermal_cooling_device_ops {
120 	int (*get_max_state) (struct thermal_cooling_device *, unsigned long *);
121 	int (*get_cur_state) (struct thermal_cooling_device *, unsigned long *);
122 	int (*set_cur_state) (struct thermal_cooling_device *, unsigned long);
123 	int (*get_requested_power)(struct thermal_cooling_device *,
124 				   struct thermal_zone_device *, u32 *);
125 	int (*state2power)(struct thermal_cooling_device *,
126 			   struct thermal_zone_device *, unsigned long, u32 *);
127 	int (*power2state)(struct thermal_cooling_device *,
128 			   struct thermal_zone_device *, u32, unsigned long *);
129 };
130 
131 struct thermal_cooling_device {
132 	int id;
133 	char type[THERMAL_NAME_LENGTH];
134 	struct device device;
135 	struct device_node *np;
136 	void *devdata;
137 	const struct thermal_cooling_device_ops *ops;
138 	bool updated; /* true if the cooling device does not need update */
139 	struct mutex lock; /* protect thermal_instances list */
140 	struct list_head thermal_instances;
141 	struct list_head node;
142 };
143 
144 struct thermal_attr {
145 	struct device_attribute attr;
146 	char name[THERMAL_NAME_LENGTH];
147 };
148 
149 /**
150  * struct thermal_zone_device - structure for a thermal zone
151  * @id:		unique id number for each thermal zone
152  * @type:	the thermal zone device type
153  * @device:	&struct device for this thermal zone
154  * @trip_temp_attrs:	attributes for trip points for sysfs: trip temperature
155  * @trip_type_attrs:	attributes for trip points for sysfs: trip type
156  * @trip_hyst_attrs:	attributes for trip points for sysfs: trip hysteresis
157  * @devdata:	private pointer for device private data
158  * @trips:	number of trip points the thermal zone supports
159  * @trips_disabled;	bitmap for disabled trips
160  * @passive_delay:	number of milliseconds to wait between polls when
161  *			performing passive cooling.
162  * @polling_delay:	number of milliseconds to wait between polls when
163  *			checking whether trip points have been crossed (0 for
164  *			interrupt driven systems)
165  * @temperature:	current temperature.  This is only for core code,
166  *			drivers should use thermal_zone_get_temp() to get the
167  *			current temperature
168  * @last_temperature:	previous temperature read
169  * @emul_temperature:	emulated temperature when using CONFIG_THERMAL_EMULATION
170  * @passive:		1 if you've crossed a passive trip point, 0 otherwise.
171  * @forced_passive:	If > 0, temperature at which to switch on all ACPI
172  *			processor cooling devices.  Currently only used by the
173  *			step-wise governor.
174  * @need_update:	if equals 1, thermal_zone_device_update needs to be invoked.
175  * @ops:	operations this &thermal_zone_device supports
176  * @tzp:	thermal zone parameters
177  * @governor:	pointer to the governor for this thermal zone
178  * @governor_data:	private pointer for governor data
179  * @thermal_instances:	list of &struct thermal_instance of this thermal zone
180  * @idr:	&struct idr to generate unique id for this zone's cooling
181  *		devices
182  * @lock:	lock to protect thermal_instances list
183  * @node:	node in thermal_tz_list (in thermal_core.c)
184  * @poll_queue:	delayed work for polling
185  */
186 struct thermal_zone_device {
187 	int id;
188 	char type[THERMAL_NAME_LENGTH];
189 	struct device device;
190 	struct thermal_attr *trip_temp_attrs;
191 	struct thermal_attr *trip_type_attrs;
192 	struct thermal_attr *trip_hyst_attrs;
193 	void *devdata;
194 	int trips;
195 	unsigned long trips_disabled;	/* bitmap for disabled trips */
196 	int passive_delay;
197 	int polling_delay;
198 	int temperature;
199 	int last_temperature;
200 	int emul_temperature;
201 	int passive;
202 	unsigned int forced_passive;
203 	atomic_t need_update;
204 	struct thermal_zone_device_ops *ops;
205 	struct thermal_zone_params *tzp;
206 	struct thermal_governor *governor;
207 	void *governor_data;
208 	struct list_head thermal_instances;
209 	struct idr idr;
210 	struct mutex lock;
211 	struct list_head node;
212 	struct delayed_work poll_queue;
213 };
214 
215 /**
216  * struct thermal_governor - structure that holds thermal governor information
217  * @name:	name of the governor
218  * @bind_to_tz: callback called when binding to a thermal zone.  If it
219  *		returns 0, the governor is bound to the thermal zone,
220  *		otherwise it fails.
221  * @unbind_from_tz:	callback called when a governor is unbound from a
222  *			thermal zone.
223  * @throttle:	callback called for every trip point even if temperature is
224  *		below the trip point temperature
225  * @governor_list:	node in thermal_governor_list (in thermal_core.c)
226  */
227 struct thermal_governor {
228 	char name[THERMAL_NAME_LENGTH];
229 	int (*bind_to_tz)(struct thermal_zone_device *tz);
230 	void (*unbind_from_tz)(struct thermal_zone_device *tz);
231 	int (*throttle)(struct thermal_zone_device *tz, int trip);
232 	struct list_head	governor_list;
233 };
234 
235 /* Structure that holds binding parameters for a zone */
236 struct thermal_bind_params {
237 	struct thermal_cooling_device *cdev;
238 
239 	/*
240 	 * This is a measure of 'how effectively these devices can
241 	 * cool 'this' thermal zone. It shall be determined by
242 	 * platform characterization. This value is relative to the
243 	 * rest of the weights so a cooling device whose weight is
244 	 * double that of another cooling device is twice as
245 	 * effective. See Documentation/thermal/sysfs-api.txt for more
246 	 * information.
247 	 */
248 	int weight;
249 
250 	/*
251 	 * This is a bit mask that gives the binding relation between this
252 	 * thermal zone and cdev, for a particular trip point.
253 	 * See Documentation/thermal/sysfs-api.txt for more information.
254 	 */
255 	int trip_mask;
256 
257 	/*
258 	 * This is an array of cooling state limits. Must have exactly
259 	 * 2 * thermal_zone.number_of_trip_points. It is an array consisting
260 	 * of tuples <lower-state upper-state> of state limits. Each trip
261 	 * will be associated with one state limit tuple when binding.
262 	 * A NULL pointer means <THERMAL_NO_LIMITS THERMAL_NO_LIMITS>
263 	 * on all trips.
264 	 */
265 	unsigned long *binding_limits;
266 	int (*match) (struct thermal_zone_device *tz,
267 			struct thermal_cooling_device *cdev);
268 };
269 
270 /* Structure to define Thermal Zone parameters */
271 struct thermal_zone_params {
272 	char governor_name[THERMAL_NAME_LENGTH];
273 
274 	/*
275 	 * a boolean to indicate if the thermal to hwmon sysfs interface
276 	 * is required. when no_hwmon == false, a hwmon sysfs interface
277 	 * will be created. when no_hwmon == true, nothing will be done
278 	 */
279 	bool no_hwmon;
280 
281 	int num_tbps;	/* Number of tbp entries */
282 	struct thermal_bind_params *tbp;
283 
284 	/*
285 	 * Sustainable power (heat) that this thermal zone can dissipate in
286 	 * mW
287 	 */
288 	u32 sustainable_power;
289 
290 	/*
291 	 * Proportional parameter of the PID controller when
292 	 * overshooting (i.e., when temperature is below the target)
293 	 */
294 	s32 k_po;
295 
296 	/*
297 	 * Proportional parameter of the PID controller when
298 	 * undershooting
299 	 */
300 	s32 k_pu;
301 
302 	/* Integral parameter of the PID controller */
303 	s32 k_i;
304 
305 	/* Derivative parameter of the PID controller */
306 	s32 k_d;
307 
308 	/* threshold below which the error is no longer accumulated */
309 	s32 integral_cutoff;
310 
311 	/*
312 	 * @slope:	slope of a linear temperature adjustment curve.
313 	 * 		Used by thermal zone drivers.
314 	 */
315 	int slope;
316 	/*
317 	 * @offset:	offset of a linear temperature adjustment curve.
318 	 * 		Used by thermal zone drivers (default 0).
319 	 */
320 	int offset;
321 };
322 
323 struct thermal_genl_event {
324 	u32 orig;
325 	enum events event;
326 };
327 
328 /**
329  * struct thermal_zone_of_device_ops - scallbacks for handling DT based zones
330  *
331  * Mandatory:
332  * @get_temp: a pointer to a function that reads the sensor temperature.
333  *
334  * Optional:
335  * @get_trend: a pointer to a function that reads the sensor temperature trend.
336  * @set_emul_temp: a pointer to a function that sets sensor emulated
337  *		   temperature.
338  */
339 struct thermal_zone_of_device_ops {
340 	int (*get_temp)(void *, int *);
341 	int (*get_trend)(void *, long *);
342 	int (*set_emul_temp)(void *, int);
343 };
344 
345 /**
346  * struct thermal_trip - representation of a point in temperature domain
347  * @np: pointer to struct device_node that this trip point was created from
348  * @temperature: temperature value in miliCelsius
349  * @hysteresis: relative hysteresis in miliCelsius
350  * @type: trip point type
351  */
352 
353 struct thermal_trip {
354 	struct device_node *np;
355 	unsigned long int temperature;
356 	unsigned long int hysteresis;
357 	enum thermal_trip_type type;
358 };
359 
360 /* Function declarations */
361 #ifdef CONFIG_THERMAL_OF
362 struct thermal_zone_device *
363 thermal_zone_of_sensor_register(struct device *dev, int id, void *data,
364 				const struct thermal_zone_of_device_ops *ops);
365 void thermal_zone_of_sensor_unregister(struct device *dev,
366 				       struct thermal_zone_device *tz);
367 #else
368 static inline struct thermal_zone_device *
thermal_zone_of_sensor_register(struct device * dev,int id,void * data,const struct thermal_zone_of_device_ops * ops)369 thermal_zone_of_sensor_register(struct device *dev, int id, void *data,
370 				const struct thermal_zone_of_device_ops *ops)
371 {
372 	return ERR_PTR(-ENODEV);
373 }
374 
375 static inline
thermal_zone_of_sensor_unregister(struct device * dev,struct thermal_zone_device * tz)376 void thermal_zone_of_sensor_unregister(struct device *dev,
377 				       struct thermal_zone_device *tz)
378 {
379 }
380 
381 #endif
382 
383 #if IS_ENABLED(CONFIG_THERMAL)
cdev_is_power_actor(struct thermal_cooling_device * cdev)384 static inline bool cdev_is_power_actor(struct thermal_cooling_device *cdev)
385 {
386 	return cdev->ops->get_requested_power && cdev->ops->state2power &&
387 		cdev->ops->power2state;
388 }
389 
390 int power_actor_get_max_power(struct thermal_cooling_device *,
391 			      struct thermal_zone_device *tz, u32 *max_power);
392 int power_actor_get_min_power(struct thermal_cooling_device *,
393 			      struct thermal_zone_device *tz, u32 *min_power);
394 int power_actor_set_power(struct thermal_cooling_device *,
395 			  struct thermal_instance *, u32);
396 struct thermal_zone_device *thermal_zone_device_register(const char *, int, int,
397 		void *, struct thermal_zone_device_ops *,
398 		struct thermal_zone_params *, int, int);
399 void thermal_zone_device_unregister(struct thermal_zone_device *);
400 
401 int thermal_zone_bind_cooling_device(struct thermal_zone_device *, int,
402 				     struct thermal_cooling_device *,
403 				     unsigned long, unsigned long,
404 				     unsigned int);
405 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *, int,
406 				       struct thermal_cooling_device *);
407 void thermal_zone_device_update(struct thermal_zone_device *);
408 
409 struct thermal_cooling_device *thermal_cooling_device_register(char *, void *,
410 		const struct thermal_cooling_device_ops *);
411 struct thermal_cooling_device *
412 thermal_of_cooling_device_register(struct device_node *np, char *, void *,
413 				   const struct thermal_cooling_device_ops *);
414 void thermal_cooling_device_unregister(struct thermal_cooling_device *);
415 struct thermal_zone_device *thermal_zone_get_zone_by_name(const char *name);
416 int thermal_zone_get_temp(struct thermal_zone_device *tz, int *temp);
417 
418 int get_tz_trend(struct thermal_zone_device *, int);
419 struct thermal_instance *get_thermal_instance(struct thermal_zone_device *,
420 		struct thermal_cooling_device *, int);
421 void thermal_cdev_update(struct thermal_cooling_device *);
422 void thermal_notify_framework(struct thermal_zone_device *, int);
423 #else
cdev_is_power_actor(struct thermal_cooling_device * cdev)424 static inline bool cdev_is_power_actor(struct thermal_cooling_device *cdev)
425 { return false; }
power_actor_get_max_power(struct thermal_cooling_device * cdev,struct thermal_zone_device * tz,u32 * max_power)426 static inline int power_actor_get_max_power(struct thermal_cooling_device *cdev,
427 			      struct thermal_zone_device *tz, u32 *max_power)
428 { return 0; }
power_actor_get_min_power(struct thermal_cooling_device * cdev,struct thermal_zone_device * tz,u32 * min_power)429 static inline int power_actor_get_min_power(struct thermal_cooling_device *cdev,
430 					    struct thermal_zone_device *tz,
431 					    u32 *min_power)
432 { return -ENODEV; }
power_actor_set_power(struct thermal_cooling_device * cdev,struct thermal_instance * tz,u32 power)433 static inline int power_actor_set_power(struct thermal_cooling_device *cdev,
434 			  struct thermal_instance *tz, u32 power)
435 { return 0; }
thermal_zone_device_register(const char * type,int trips,int mask,void * devdata,struct thermal_zone_device_ops * ops,const struct thermal_zone_params * tzp,int passive_delay,int polling_delay)436 static inline struct thermal_zone_device *thermal_zone_device_register(
437 	const char *type, int trips, int mask, void *devdata,
438 	struct thermal_zone_device_ops *ops,
439 	const struct thermal_zone_params *tzp,
440 	int passive_delay, int polling_delay)
441 { return ERR_PTR(-ENODEV); }
thermal_zone_device_unregister(struct thermal_zone_device * tz)442 static inline void thermal_zone_device_unregister(
443 	struct thermal_zone_device *tz)
444 { }
thermal_zone_bind_cooling_device(struct thermal_zone_device * tz,int trip,struct thermal_cooling_device * cdev,unsigned long upper,unsigned long lower,unsigned int weight)445 static inline int thermal_zone_bind_cooling_device(
446 	struct thermal_zone_device *tz, int trip,
447 	struct thermal_cooling_device *cdev,
448 	unsigned long upper, unsigned long lower,
449 	unsigned int weight)
450 { return -ENODEV; }
thermal_zone_unbind_cooling_device(struct thermal_zone_device * tz,int trip,struct thermal_cooling_device * cdev)451 static inline int thermal_zone_unbind_cooling_device(
452 	struct thermal_zone_device *tz, int trip,
453 	struct thermal_cooling_device *cdev)
454 { return -ENODEV; }
thermal_zone_device_update(struct thermal_zone_device * tz)455 static inline void thermal_zone_device_update(struct thermal_zone_device *tz)
456 { }
457 static inline struct thermal_cooling_device *
thermal_cooling_device_register(char * type,void * devdata,const struct thermal_cooling_device_ops * ops)458 thermal_cooling_device_register(char *type, void *devdata,
459 	const struct thermal_cooling_device_ops *ops)
460 { return ERR_PTR(-ENODEV); }
461 static inline struct thermal_cooling_device *
thermal_of_cooling_device_register(struct device_node * np,char * type,void * devdata,const struct thermal_cooling_device_ops * ops)462 thermal_of_cooling_device_register(struct device_node *np,
463 	char *type, void *devdata, const struct thermal_cooling_device_ops *ops)
464 { return ERR_PTR(-ENODEV); }
thermal_cooling_device_unregister(struct thermal_cooling_device * cdev)465 static inline void thermal_cooling_device_unregister(
466 	struct thermal_cooling_device *cdev)
467 { }
thermal_zone_get_zone_by_name(const char * name)468 static inline struct thermal_zone_device *thermal_zone_get_zone_by_name(
469 		const char *name)
470 { return ERR_PTR(-ENODEV); }
thermal_zone_get_temp(struct thermal_zone_device * tz,int * temp)471 static inline int thermal_zone_get_temp(
472 		struct thermal_zone_device *tz, int *temp)
473 { return -ENODEV; }
get_tz_trend(struct thermal_zone_device * tz,int trip)474 static inline int get_tz_trend(struct thermal_zone_device *tz, int trip)
475 { return -ENODEV; }
476 static inline struct thermal_instance *
get_thermal_instance(struct thermal_zone_device * tz,struct thermal_cooling_device * cdev,int trip)477 get_thermal_instance(struct thermal_zone_device *tz,
478 	struct thermal_cooling_device *cdev, int trip)
479 { return ERR_PTR(-ENODEV); }
thermal_cdev_update(struct thermal_cooling_device * cdev)480 static inline void thermal_cdev_update(struct thermal_cooling_device *cdev)
481 { }
thermal_notify_framework(struct thermal_zone_device * tz,int trip)482 static inline void thermal_notify_framework(struct thermal_zone_device *tz,
483 	int trip)
484 { }
485 #endif /* CONFIG_THERMAL */
486 
487 #if defined(CONFIG_NET) && IS_ENABLED(CONFIG_THERMAL)
488 extern int thermal_generate_netlink_event(struct thermal_zone_device *tz,
489 						enum events event);
490 #else
thermal_generate_netlink_event(struct thermal_zone_device * tz,enum events event)491 static inline int thermal_generate_netlink_event(struct thermal_zone_device *tz,
492 						enum events event)
493 {
494 	return 0;
495 }
496 #endif
497 
498 #endif /* __THERMAL_H__ */
499