LXR linux/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#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
  46struct thermal_zone_device;
  47struct thermal_cooling_device;
  48struct thermal_instance;
  49
  50enum thermal_device_mode {
  51        THERMAL_DEVICE_DISABLED = 0,
  52        THERMAL_DEVICE_ENABLED,
  53};
  54
  55enum thermal_trip_type {
  56        THERMAL_TRIP_ACTIVE = 0,
  57        THERMAL_TRIP_PASSIVE,
  58        THERMAL_TRIP_HOT,
  59        THERMAL_TRIP_CRITICAL,
  60};
  61
  62enum 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 */
  71enum 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
  82struct 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
 107struct 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
 119struct 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
 133struct 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 */
 180struct 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 */
 225struct 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 */
 234struct 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 */
 269struct 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
 321struct 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 */
 342struct 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
 358struct 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
 367int thermal_zone_of_get_sensor_id(struct device_node *tz_np,
 368                                  struct device_node *sensor_np,
 369                                  u32 *id);
 370struct thermal_zone_device *
 371thermal_zone_of_sensor_register(struct device *dev, int id, void *data,
 372                                const struct thermal_zone_of_device_ops *ops);
 373void thermal_zone_of_sensor_unregister(struct device *dev,
 374                                       struct thermal_zone_device *tz);
 375struct 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);
 378void devm_thermal_zone_of_sensor_unregister(struct device *dev,
 379                                            struct thermal_zone_device *tz);
 380#else
 381
 382static 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}
 388static inline struct thermal_zone_device *
 389thermal_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
 395static inline
 396void thermal_zone_of_sensor_unregister(struct device *dev,
 397                                       struct thermal_zone_device *tz)
 398{
 399}
 400
 401static 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
 408static inline
 409void 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)
 417static 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
 423int power_actor_get_max_power(struct thermal_cooling_device *,
 424                              struct thermal_zone_device *tz, u32 *max_power);
 425int power_actor_get_min_power(struct thermal_cooling_device *,
 426                              struct thermal_zone_device *tz, u32 *min_power);
 427int power_actor_set_power(struct thermal_cooling_device *,
 428                          struct thermal_instance *, u32);
 429struct 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);
 432void thermal_zone_device_unregister(struct thermal_zone_device *);
 433
 434int thermal_zone_bind_cooling_device(struct thermal_zone_device *, int,
 435                                     struct thermal_cooling_device *,
 436                                     unsigned long, unsigned long,
 437                                     unsigned int);
 438int thermal_zone_unbind_cooling_device(struct thermal_zone_device *, int,
 439                                       struct thermal_cooling_device *);
 440void thermal_zone_device_update(struct thermal_zone_device *,
 441                                enum thermal_notify_event);
 442void thermal_zone_set_trips(struct thermal_zone_device *);
 443
 444struct thermal_cooling_device *thermal_cooling_device_register(const char *,
 445                void *, const struct thermal_cooling_device_ops *);
 446struct thermal_cooling_device *
 447thermal_of_cooling_device_register(struct device_node *np, const char *, void *,
 448                                   const struct thermal_cooling_device_ops *);
 449struct thermal_cooling_device *
 450devm_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);
 454void thermal_cooling_device_unregister(struct thermal_cooling_device *);
 455struct thermal_zone_device *thermal_zone_get_zone_by_name(const char *name);
 456int thermal_zone_get_temp(struct thermal_zone_device *tz, int *temp);
 457int thermal_zone_get_slope(struct thermal_zone_device *tz);
 458int thermal_zone_get_offset(struct thermal_zone_device *tz);
 459
 460int get_tz_trend(struct thermal_zone_device *, int);
 461struct thermal_instance *get_thermal_instance(struct thermal_zone_device *,
 462                struct thermal_cooling_device *, int);
 463void thermal_cdev_update(struct thermal_cooling_device *);
 464void thermal_notify_framework(struct thermal_zone_device *, int);
 465#else
 466static inline bool cdev_is_power_actor(struct thermal_cooling_device *cdev)
 467{ return false; }
 468static inline int power_actor_get_max_power(struct thermal_cooling_device *cdev,
 469                              struct thermal_zone_device *tz, u32 *max_power)
 470{ return 0; }
 471static 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; }
 475static inline int power_actor_set_power(struct thermal_cooling_device *cdev,
 476                          struct thermal_instance *tz, u32 power)
 477{ return 0; }
 478static 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); }
 484static inline void thermal_zone_device_unregister(
 485        struct thermal_zone_device *tz)
 486{ }
 487static 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; }
 493static inline int thermal_zone_unbind_cooling_device(
 494        struct thermal_zone_device *tz, int trip,
 495        struct thermal_cooling_device *cdev)
 496{ return -ENODEV; }
 497static inline void thermal_zone_device_update(struct thermal_zone_device *tz,
 498                                              enum thermal_notify_event event)
 499{ }
 500static inline void thermal_zone_set_trips(struct thermal_zone_device *tz)
 501{ }
 502static inline struct thermal_cooling_device *
 503thermal_cooling_device_register(char *type, void *devdata,
 504        const struct thermal_cooling_device_ops *ops)
 505{ return ERR_PTR(-ENODEV); }
 506static inline struct thermal_cooling_device *
 507thermal_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); }
 510static inline struct thermal_cooling_device *
 511devm_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}
 518static inline void thermal_cooling_device_unregister(
 519        struct thermal_cooling_device *cdev)
 520{ }
 521static inline struct thermal_zone_device *thermal_zone_get_zone_by_name(
 522                const char *name)
 523{ return ERR_PTR(-ENODEV); }
 524static inline int thermal_zone_get_temp(
 525                struct thermal_zone_device *tz, int *temp)
 526{ return -ENODEV; }
 527static inline int thermal_zone_get_slope(
 528                struct thermal_zone_device *tz)
 529{ return -ENODEV; }
 530static inline int thermal_zone_get_offset(
 531                struct thermal_zone_device *tz)
 532{ return -ENODEV; }
 533static inline int get_tz_trend(struct thermal_zone_device *tz, int trip)
 534{ return -ENODEV; }
 535static inline struct thermal_instance *
 536get_thermal_instance(struct thermal_zone_device *tz,
 537        struct thermal_cooling_device *cdev, int trip)
 538{ return ERR_PTR(-ENODEV); }
 539static inline void thermal_cdev_update(struct thermal_cooling_device *cdev)
 540{ }
 541static inline void thermal_notify_framework(struct thermal_zone_device *tz,
 542        int trip)
 543{ }
 544#endif /* CONFIG_THERMAL */
 545
 546#endif /* __THERMAL_H__ */
 547