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