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 32struct thermal_zone_device; 33struct thermal_cooling_device; 34struct thermal_instance; 35struct thermal_debugfs; 36struct thermal_attr; 37 38enum 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 */ 45enum 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 */ 69struct 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 84struct 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 102struct 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 111struct 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 */ 171struct 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 */ 223struct 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 */ 235struct 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 286struct thermal_zone_device *devm_thermal_of_zone_register(struct device *dev, int id, void *data, 287 const struct thermal_zone_device_ops *ops); 288 289void devm_thermal_of_zone_unregister(struct device *dev, struct thermal_zone_device *tz); 290 291#else 292 293static inline 294struct 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 300static inline void devm_thermal_of_zone_unregister(struct device *dev, 301 struct thermal_zone_device *tz) 302{ 303} 304#endif 305 306int __thermal_zone_get_trip(struct thermal_zone_device *tz, int trip_id, 307 struct thermal_trip *trip); 308int thermal_zone_get_trip(struct thermal_zone_device *tz, int trip_id, 309 struct thermal_trip *trip); 310int for_each_thermal_trip(struct thermal_zone_device *tz, 311 int (*cb)(struct thermal_trip *, void *), 312 void *data); 313int thermal_zone_for_each_trip(struct thermal_zone_device *tz, 314 int (*cb)(struct thermal_trip *, void *), 315 void *data); 316int thermal_zone_get_num_trips(struct thermal_zone_device *tz); 317void thermal_zone_set_trip_temp(struct thermal_zone_device *tz, 318 struct thermal_trip *trip, int temp); 319 320int thermal_zone_get_crit_temp(struct thermal_zone_device *tz, int *temp); 321 322#ifdef CONFIG_THERMAL 323struct 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 331struct 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 337void thermal_zone_device_unregister(struct thermal_zone_device *tz); 338 339void *thermal_zone_device_priv(struct thermal_zone_device *tzd); 340const char *thermal_zone_device_type(struct thermal_zone_device *tzd); 341int thermal_zone_device_id(struct thermal_zone_device *tzd); 342struct device *thermal_zone_device(struct thermal_zone_device *tzd); 343 344int 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); 349int thermal_zone_bind_cooling_device(struct thermal_zone_device *, int, 350 struct thermal_cooling_device *, 351 unsigned long, unsigned long, 352 unsigned int); 353int thermal_unbind_cdev_from_trip(struct thermal_zone_device *tz, 354 const struct thermal_trip *trip, 355 struct thermal_cooling_device *cdev); 356int thermal_zone_unbind_cooling_device(struct thermal_zone_device *, int, 357 struct thermal_cooling_device *); 358void thermal_zone_device_update(struct thermal_zone_device *, 359 enum thermal_notify_event); 360 361struct thermal_cooling_device *thermal_cooling_device_register(const char *, 362 void *, const struct thermal_cooling_device_ops *); 363struct thermal_cooling_device * 364thermal_of_cooling_device_register(struct device_node *np, const char *, void *, 365 const struct thermal_cooling_device_ops *); 366struct thermal_cooling_device * 367devm_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); 371void thermal_cooling_device_update(struct thermal_cooling_device *); 372void thermal_cooling_device_unregister(struct thermal_cooling_device *); 373struct thermal_zone_device *thermal_zone_get_zone_by_name(const char *name); 374int thermal_zone_get_temp(struct thermal_zone_device *tz, int *temp); 375int thermal_zone_get_slope(struct thermal_zone_device *tz); 376int thermal_zone_get_offset(struct thermal_zone_device *tz); 377 378int thermal_zone_device_enable(struct thermal_zone_device *tz); 379int thermal_zone_device_disable(struct thermal_zone_device *tz); 380void thermal_zone_device_critical(struct thermal_zone_device *tz); 381#else 382static 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 391static 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 398static inline void thermal_zone_device_unregister(struct thermal_zone_device *tz) 399{ } 400 401static inline struct thermal_cooling_device * 402thermal_cooling_device_register(const char *type, void *devdata, 403 const struct thermal_cooling_device_ops *ops) 404{ return ERR_PTR(-ENODEV); } 405static inline struct thermal_cooling_device * 406thermal_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); } 410static inline struct thermal_cooling_device * 411devm_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} 418static inline void thermal_cooling_device_unregister( 419 struct thermal_cooling_device *cdev) 420{ } 421static inline struct thermal_zone_device *thermal_zone_get_zone_by_name( 422 const char *name) 423{ return ERR_PTR(-ENODEV); } 424static inline int thermal_zone_get_temp( 425 struct thermal_zone_device *tz, int *temp) 426{ return -ENODEV; } 427static inline int thermal_zone_get_slope( 428 struct thermal_zone_device *tz) 429{ return -ENODEV; } 430static inline int thermal_zone_get_offset( 431 struct thermal_zone_device *tz) 432{ return -ENODEV; } 433 434static inline void *thermal_zone_device_priv(struct thermal_zone_device *tz) 435{ 436 return NULL; 437} 438 439static inline const char *thermal_zone_device_type(struct thermal_zone_device *tzd) 440{ 441 return NULL; 442} 443 444static inline int thermal_zone_device_id(struct thermal_zone_device *tzd) 445{ 446 return -ENODEV; 447} 448 449static inline int thermal_zone_device_enable(struct thermal_zone_device *tz) 450{ return -ENODEV; } 451 452static inline int thermal_zone_device_disable(struct thermal_zone_device *tz) 453{ return -ENODEV; } 454#endif /* CONFIG_THERMAL */ 455 456#endif /* __THERMAL_H__ */ 457