include/linux/thermal.h

   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
  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         THERMAL_TZ_RESUME, /* Thermal zone is resuming after system sleep */
  59         THERMAL_TZ_ADD_THRESHOLD, /* Threshold added */
  60         THERMAL_TZ_DEL_THRESHOLD, /* Threshold deleted */
  61         THERMAL_TZ_FLUSH_THRESHOLDS, /* All thresholds deleted */
  62 };
  63
  64 /**
  65  * struct thermal_trip - representation of a point in temperature domain
  66  * @temperature: temperature value in miliCelsius
  67  * @hysteresis: relative hysteresis in miliCelsius
  68  * @type: trip point type
  69  * @priv: pointer to driver data associated with this trip
  70  * @flags: flags representing binary properties of the trip
  71  */
  72 struct thermal_trip {
  73         int temperature;
  74         int hysteresis;
  75         enum thermal_trip_type type;
  76         u8 flags;
  77         void *priv;
  78 };
  79
  80 #define THERMAL_TRIP_FLAG_RW_TEMP       BIT(0)
  81 #define THERMAL_TRIP_FLAG_RW_HYST       BIT(1)
  82
  83 #define THERMAL_TRIP_FLAG_RW    (THERMAL_TRIP_FLAG_RW_TEMP | \
  84                                  THERMAL_TRIP_FLAG_RW_HYST)
  85
  86 #define THERMAL_TRIP_PRIV_TO_INT(_val_) (uintptr_t)(_val_)
  87 #define THERMAL_INT_TO_TRIP_PRIV(_val_) (void *)(uintptr_t)(_val_)
  88
  89 struct thermal_zone_device;
  90
  91 struct cooling_spec {
  92         unsigned long upper;    /* Highest cooling state  */
  93         unsigned long lower;    /* Lowest cooling state  */
  94         unsigned int weight;    /* Cooling device weight */
  95 };
  96
  97 struct thermal_zone_device_ops {
  98         bool (*should_bind) (struct thermal_zone_device *,
  99                              const struct thermal_trip *,
 100                              struct thermal_cooling_device *,
 101                              struct cooling_spec *);
 102         int (*get_temp) (struct thermal_zone_device *, int *);
 103         int (*set_trips) (struct thermal_zone_device *, int, int);
 104         int (*change_mode) (struct thermal_zone_device *,
 105                 enum thermal_device_mode);
 106         int (*set_trip_temp) (struct thermal_zone_device *,
 107                               const struct thermal_trip *, int);
 108         int (*get_crit_temp) (struct thermal_zone_device *, int *);
 109         int (*set_emul_temp) (struct thermal_zone_device *, int);
 110         int (*get_trend) (struct thermal_zone_device *,
 111                           const struct thermal_trip *, enum thermal_trend *);
 112         void (*hot)(struct thermal_zone_device *);
 113         void (*critical)(struct thermal_zone_device *);
 114 };
 115
 116 struct thermal_cooling_device_ops {
 117         int (*get_max_state) (struct thermal_cooling_device *, unsigned long *);
 118         int (*get_cur_state) (struct thermal_cooling_device *, unsigned long *);
 119         int (*set_cur_state) (struct thermal_cooling_device *, unsigned long);
 120         int (*get_requested_power)(struct thermal_cooling_device *, u32 *);
 121         int (*state2power)(struct thermal_cooling_device *, unsigned long, u32 *);
 122         int (*power2state)(struct thermal_cooling_device *, u32, unsigned long *);
 123 };
 124
 125 struct thermal_cooling_device {
 126         int id;
 127         const char *type;
 128         unsigned long max_state;
 129         struct device device;
 130         struct device_node *np;
 131         void *devdata;
 132         void *stats;
 133         const struct thermal_cooling_device_ops *ops;
 134         bool updated; /* true if the cooling device does not need update */
 135         struct mutex lock; /* protect thermal_instances list */
 136         struct list_head thermal_instances;
 137         struct list_head node;
 138 #ifdef CONFIG_THERMAL_DEBUGFS
 139         struct thermal_debugfs *debugfs;
 140 #endif
 141 };
 142
 143 DEFINE_GUARD(cooling_dev, struct thermal_cooling_device *, mutex_lock(&_T->lock),
 144              mutex_unlock(&_T->lock))
 145
 146 /* Structure to define Thermal Zone parameters */
 147 struct thermal_zone_params {
 148         const char *governor_name;
 149
 150         /*
 151          * a boolean to indicate if the thermal to hwmon sysfs interface
 152          * is required. when no_hwmon == false, a hwmon sysfs interface
 153          * will be created. when no_hwmon == true, nothing will be done
 154          */
 155         bool no_hwmon;
 156
 157         /*
 158          * Sustainable power (heat) that this thermal zone can dissipate in
 159          * mW
 160          */
 161         u32 sustainable_power;
 162
 163         /*
 164          * Proportional parameter of the PID controller when
 165          * overshooting (i.e., when temperature is below the target)
 166          */
 167         s32 k_po;
 168
 169         /*
 170          * Proportional parameter of the PID controller when
 171          * undershooting
 172          */
 173         s32 k_pu;
 174
 175         /* Integral parameter of the PID controller */
 176         s32 k_i;
 177
 178         /* Derivative parameter of the PID controller */
 179         s32 k_d;
 180
 181         /* threshold below which the error is no longer accumulated */
 182         s32 integral_cutoff;
 183
 184         /*
 185          * @slope:      slope of a linear temperature adjustment curve.
 186          *              Used by thermal zone drivers.
 187          */
 188         int slope;
 189         /*
 190          * @offset:     offset of a linear temperature adjustment curve.
 191          *              Used by thermal zone drivers (default 0).
 192          */
 193         int offset;
 194 };
 195
 196 /* Function declarations */
 197 #ifdef CONFIG_THERMAL_OF
 198 struct thermal_zone_device *devm_thermal_of_zone_register(struct device *dev, int id, void *data,
 199                                                           const struct thermal_zone_device_ops *ops);
 200
 201 void devm_thermal_of_zone_unregister(struct device *dev, struct thermal_zone_device *tz);
 202
 203 #else
 204
 205 static inline
 206 struct thermal_zone_device *devm_thermal_of_zone_register(struct device *dev, int id, void *data,
 207                                                           const struct thermal_zone_device_ops *ops)
 208 {
 209         return ERR_PTR(-ENOTSUPP);
 210 }
 211
 212 static inline void devm_thermal_of_zone_unregister(struct device *dev,
 213                                                    struct thermal_zone_device *tz)
 214 {
 215 }
 216 #endif
 217
 218 int for_each_thermal_trip(struct thermal_zone_device *tz,
 219                           int (*cb)(struct thermal_trip *, void *),
 220                           void *data);
 221 int thermal_zone_for_each_trip(struct thermal_zone_device *tz,
 222                                int (*cb)(struct thermal_trip *, void *),
 223                                void *data);
 224 void thermal_zone_set_trip_temp(struct thermal_zone_device *tz,
 225                                 struct thermal_trip *trip, int temp);
 226
 227 int thermal_zone_get_crit_temp(struct thermal_zone_device *tz, int *temp);
 228
 229 #ifdef CONFIG_THERMAL
 230 struct thermal_zone_device *thermal_zone_device_register_with_trips(
 231                                         const char *type,
 232                                         const struct thermal_trip *trips,
 233                                         int num_trips, void *devdata,
 234                                         const struct thermal_zone_device_ops *ops,
 235                                         const struct thermal_zone_params *tzp,
 236                                         unsigned int passive_delay,
 237                                         unsigned int polling_delay);
 238
 239 struct thermal_zone_device *thermal_tripless_zone_device_register(
 240                                         const char *type,
 241                                         void *devdata,
 242                                         const struct thermal_zone_device_ops *ops,
 243                                         const struct thermal_zone_params *tzp);
 244
 245 void thermal_zone_device_unregister(struct thermal_zone_device *tz);
 246
 247 void *thermal_zone_device_priv(struct thermal_zone_device *tzd);
 248 const char *thermal_zone_device_type(struct thermal_zone_device *tzd);
 249 int thermal_zone_device_id(struct thermal_zone_device *tzd);
 250 struct device *thermal_zone_device(struct thermal_zone_device *tzd);
 251
 252 void thermal_zone_device_update(struct thermal_zone_device *,
 253                                 enum thermal_notify_event);
 254
 255 struct thermal_cooling_device *thermal_cooling_device_register(const char *,
 256                 void *, const struct thermal_cooling_device_ops *);
 257 struct thermal_cooling_device *
 258 thermal_of_cooling_device_register(struct device_node *np, const char *, void *,
 259                                    const struct thermal_cooling_device_ops *);
 260 struct thermal_cooling_device *
 261 devm_thermal_of_cooling_device_register(struct device *dev,
 262                                 struct device_node *np,
 263                                 const char *type, void *devdata,
 264                                 const struct thermal_cooling_device_ops *ops);
 265 void thermal_cooling_device_update(struct thermal_cooling_device *);
 266 void thermal_cooling_device_unregister(struct thermal_cooling_device *);
 267 struct thermal_zone_device *thermal_zone_get_zone_by_name(const char *name);
 268 int thermal_zone_get_temp(struct thermal_zone_device *tz, int *temp);
 269 int thermal_zone_get_slope(struct thermal_zone_device *tz);
 270 int thermal_zone_get_offset(struct thermal_zone_device *tz);
 271 bool thermal_trip_is_bound_to_cdev(struct thermal_zone_device *tz,
 272                                    const struct thermal_trip *trip,
 273                                    struct thermal_cooling_device *cdev);
 274
 275 int thermal_zone_device_enable(struct thermal_zone_device *tz);
 276 int thermal_zone_device_disable(struct thermal_zone_device *tz);
 277 void thermal_zone_device_critical(struct thermal_zone_device *tz);
 278 #else
 279 static inline struct thermal_zone_device *thermal_zone_device_register_with_trips(
 280                                         const char *type,
 281                                         const struct thermal_trip *trips,
 282                                         int num_trips, void *devdata,
 283                                         const struct thermal_zone_device_ops *ops,
 284                                         const struct thermal_zone_params *tzp,
 285                                         int passive_delay, int polling_delay)
 286 { return ERR_PTR(-ENODEV); }
 287
 288 static inline struct thermal_zone_device *thermal_tripless_zone_device_register(
 289                                         const char *type,
 290                                         void *devdata,
 291                                         struct thermal_zone_device_ops *ops,
 292                                         const struct thermal_zone_params *tzp)
 293 { return ERR_PTR(-ENODEV); }
 294
 295 static inline void thermal_zone_device_unregister(struct thermal_zone_device *tz)
 296 { }
 297
 298 static inline struct thermal_cooling_device *
 299 thermal_cooling_device_register(const char *type, void *devdata,
 300         const struct thermal_cooling_device_ops *ops)
 301 { return ERR_PTR(-ENODEV); }
 302 static inline struct thermal_cooling_device *
 303 thermal_of_cooling_device_register(struct device_node *np,
 304         const char *type, void *devdata,
 305         const struct thermal_cooling_device_ops *ops)
 306 { return ERR_PTR(-ENODEV); }
 307 static inline struct thermal_cooling_device *
 308 devm_thermal_of_cooling_device_register(struct device *dev,
 309                                 struct device_node *np,
 310                                 const char *type, void *devdata,
 311                                 const struct thermal_cooling_device_ops *ops)
 312 {
 313         return ERR_PTR(-ENODEV);
 314 }
 315 static inline void thermal_cooling_device_unregister(
 316         struct thermal_cooling_device *cdev)
 317 { }
 318 static inline struct thermal_zone_device *thermal_zone_get_zone_by_name(
 319                 const char *name)
 320 { return ERR_PTR(-ENODEV); }
 321 static inline int thermal_zone_get_temp(
 322                 struct thermal_zone_device *tz, int *temp)
 323 { return -ENODEV; }
 324 static inline int thermal_zone_get_slope(
 325                 struct thermal_zone_device *tz)
 326 { return -ENODEV; }
 327 static inline int thermal_zone_get_offset(
 328                 struct thermal_zone_device *tz)
 329 { return -ENODEV; }
 330
 331 static inline void *thermal_zone_device_priv(struct thermal_zone_device *tz)
 332 {
 333         return NULL;
 334 }
 335
 336 static inline const char *thermal_zone_device_type(struct thermal_zone_device *tzd)
 337 {
 338         return NULL;
 339 }
 340
 341 static inline int thermal_zone_device_id(struct thermal_zone_device *tzd)
 342 {
 343         return -ENODEV;
 344 }
 345
 346 static inline int thermal_zone_device_enable(struct thermal_zone_device *tz)
 347 { return -ENODEV; }
 348
 349 static inline int thermal_zone_device_disable(struct thermal_zone_device *tz)
 350 { return -ENODEV; }
 351 #endif /* CONFIG_THERMAL */
 352
 353 #endif /* __THERMAL_H__ */