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