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