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