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