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