LXR linux/include/linux/thermal.h

   1/*
   2 *  thermal.h  ($Revision: 0 $)
   3 *
   4 *  Copyright (C) 2008  Intel Corp
   5 *  Copyright (C) 2008  Zhang Rui <rui.zhang@intel.com>
   6 *  Copyright (C) 2008  Sujith Thomas <sujith.thomas@intel.com>
   7 *
   8 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   9 *  This program is free software; you can redistribute it and/or modify
  10 *  it under the terms of the GNU General Public License as published by
  11 *  the Free Software Foundation; version 2 of the License.
  12 *
  13 *  This program is distributed in the hope that it will be useful, but
  14 *  WITHOUT ANY WARRANTY; without even the implied warranty of
  15 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 *  General Public License for more details.
  17 *
  18 *  You should have received a copy of the GNU General Public License along
  19 *  with this program; if not, write to the Free Software Foundation, Inc.,
  20 *  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  21 *
  22 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23 */
  24
  25#ifndef __THERMAL_H__
  26#define __THERMAL_H__
  27
  28#include <linux/of.h>
  29#include <linux/idr.h>
  30#include <linux/device.h>
  31#include <linux/workqueue.h>
  32#include <uapi/linux/thermal.h>
  33
  34#define THERMAL_TRIPS_NONE      -1
  35#define THERMAL_MAX_TRIPS       12
  36
  37/* invalid cooling state */
  38#define THERMAL_CSTATE_INVALID -1UL
  39
  40/* No upper/lower limit requirement */
  41#define THERMAL_NO_LIMIT        ((u32)~0)
  42
  43/* Default weight of a bound cooling device */
  44#define THERMAL_WEIGHT_DEFAULT 0
  45
  46/* use value, which < 0K, to indicate an invalid/uninitialized temperature */
  47#define THERMAL_TEMP_INVALID    -274000
  48
  49/* Unit conversion macros */
  50#define DECI_KELVIN_TO_CELSIUS(t)       ({                      \
  51        long _t = (t);                                          \
  52        ((_t-2732 >= 0) ? (_t-2732+5)/10 : (_t-2732-5)/10);     \
  53})
  54#define CELSIUS_TO_DECI_KELVIN(t)       ((t)*10+2732)
  55#define DECI_KELVIN_TO_MILLICELSIUS_WITH_OFFSET(t, off) (((t) - (off)) * 100)
  56#define DECI_KELVIN_TO_MILLICELSIUS(t) DECI_KELVIN_TO_MILLICELSIUS_WITH_OFFSET(t, 2732)
  57#define MILLICELSIUS_TO_DECI_KELVIN_WITH_OFFSET(t, off) (((t) / 100) + (off))
  58#define MILLICELSIUS_TO_DECI_KELVIN(t) MILLICELSIUS_TO_DECI_KELVIN_WITH_OFFSET(t, 2732)
  59
  60/* Default Thermal Governor */
  61#if defined(CONFIG_THERMAL_DEFAULT_GOV_STEP_WISE)
  62#define DEFAULT_THERMAL_GOVERNOR       "step_wise"
  63#elif defined(CONFIG_THERMAL_DEFAULT_GOV_FAIR_SHARE)
  64#define DEFAULT_THERMAL_GOVERNOR       "fair_share"
  65#elif defined(CONFIG_THERMAL_DEFAULT_GOV_USER_SPACE)
  66#define DEFAULT_THERMAL_GOVERNOR       "user_space"
  67#elif defined(CONFIG_THERMAL_DEFAULT_GOV_POWER_ALLOCATOR)
  68#define DEFAULT_THERMAL_GOVERNOR       "power_allocator"
  69#endif
  70
  71struct thermal_zone_device;
  72struct thermal_cooling_device;
  73struct thermal_instance;
  74
  75enum thermal_device_mode {
  76        THERMAL_DEVICE_DISABLED = 0,
  77        THERMAL_DEVICE_ENABLED,
  78};
  79
  80enum thermal_trip_type {
  81        THERMAL_TRIP_ACTIVE = 0,
  82        THERMAL_TRIP_PASSIVE,
  83        THERMAL_TRIP_HOT,
  84        THERMAL_TRIP_CRITICAL,
  85};
  86
  87enum thermal_trend {
  88        THERMAL_TREND_STABLE, /* temperature is stable */
  89        THERMAL_TREND_RAISING, /* temperature is raising */
  90        THERMAL_TREND_DROPPING, /* temperature is dropping */
  91        THERMAL_TREND_RAISE_FULL, /* apply highest cooling action */
  92        THERMAL_TREND_DROP_FULL, /* apply lowest cooling action */
  93};
  94
  95struct thermal_zone_device_ops {
  96        int (*bind) (struct thermal_zone_device *,
  97                     struct thermal_cooling_device *);
  98        int (*unbind) (struct thermal_zone_device *,
  99                       struct thermal_cooling_device *);
 100        int (*get_temp) (struct thermal_zone_device *, int *);
 101        int (*get_mode) (struct thermal_zone_device *,
 102                         enum thermal_device_mode *);
 103        int (*set_mode) (struct thermal_zone_device *,
 104                enum thermal_device_mode);
 105        int (*get_trip_type) (struct thermal_zone_device *, int,
 106                enum thermal_trip_type *);
 107        int (*get_trip_temp) (struct thermal_zone_device *, int, int *);
 108        int (*set_trip_temp) (struct thermal_zone_device *, int, int);
 109        int (*get_trip_hyst) (struct thermal_zone_device *, int, int *);
 110        int (*set_trip_hyst) (struct thermal_zone_device *, int, int);
 111        int (*get_crit_temp) (struct thermal_zone_device *, int *);
 112        int (*set_emul_temp) (struct thermal_zone_device *, int);
 113        int (*get_trend) (struct thermal_zone_device *, int,
 114                          enum thermal_trend *);
 115        int (*notify) (struct thermal_zone_device *, int,
 116                       enum thermal_trip_type);
 117};
 118
 119struct thermal_cooling_device_ops {
 120        int (*get_max_state) (struct thermal_cooling_device *, unsigned long *);
 121        int (*get_cur_state) (struct thermal_cooling_device *, unsigned long *);
 122        int (*set_cur_state) (struct thermal_cooling_device *, unsigned long);
 123        int (*get_requested_power)(struct thermal_cooling_device *,
 124                                   struct thermal_zone_device *, u32 *);
 125        int (*state2power)(struct thermal_cooling_device *,
 126                           struct thermal_zone_device *, unsigned long, u32 *);
 127        int (*power2state)(struct thermal_cooling_device *,
 128                           struct thermal_zone_device *, u32, unsigned long *);
 129};
 130
 131struct thermal_cooling_device {
 132        int id;
 133        char type[THERMAL_NAME_LENGTH];
 134        struct device device;
 135        struct device_node *np;
 136        void *devdata;
 137        const struct thermal_cooling_device_ops *ops;
 138        bool updated; /* true if the cooling device does not need update */
 139        struct mutex lock; /* protect thermal_instances list */
 140        struct list_head thermal_instances;
 141        struct list_head node;
 142};
 143
 144struct thermal_attr {
 145        struct device_attribute attr;
 146        char name[THERMAL_NAME_LENGTH];
 147};
 148
 149/**
 150 * struct thermal_zone_device - structure for a thermal zone
 151 * @id:         unique id number for each thermal zone
 152 * @type:       the thermal zone device type
 153 * @device:     &struct device for this thermal zone
 154 * @trip_temp_attrs:    attributes for trip points for sysfs: trip temperature
 155 * @trip_type_attrs:    attributes for trip points for sysfs: trip type
 156 * @trip_hyst_attrs:    attributes for trip points for sysfs: trip hysteresis
 157 * @devdata:    private pointer for device private data
 158 * @trips:      number of trip points the thermal zone supports
 159 * @trips_disabled;     bitmap for disabled trips
 160 * @passive_delay:      number of milliseconds to wait between polls when
 161 *                      performing passive cooling.
 162 * @polling_delay:      number of milliseconds to wait between polls when
 163 *                      checking whether trip points have been crossed (0 for
 164 *                      interrupt driven systems)
 165 * @temperature:        current temperature.  This is only for core code,
 166 *                      drivers should use thermal_zone_get_temp() to get the
 167 *                      current temperature
 168 * @last_temperature:   previous temperature read
 169 * @emul_temperature:   emulated temperature when using CONFIG_THERMAL_EMULATION
 170 * @passive:            1 if you've crossed a passive trip point, 0 otherwise.
 171 * @forced_passive:     If > 0, temperature at which to switch on all ACPI
 172 *                      processor cooling devices.  Currently only used by the
 173 *                      step-wise governor.
 174 * @need_update:        if equals 1, thermal_zone_device_update needs to be invoked.
 175 * @ops:        operations this &thermal_zone_device supports
 176 * @tzp:        thermal zone parameters
 177 * @governor:   pointer to the governor for this thermal zone
 178 * @governor_data:      private pointer for governor data
 179 * @thermal_instances:  list of &struct thermal_instance of this thermal zone
 180 * @idr:        &struct idr to generate unique id for this zone's cooling
 181 *              devices
 182 * @lock:       lock to protect thermal_instances list
 183 * @node:       node in thermal_tz_list (in thermal_core.c)
 184 * @poll_queue: delayed work for polling
 185 */
 186struct thermal_zone_device {
 187        int id;
 188        char type[THERMAL_NAME_LENGTH];
 189        struct device device;
 190        struct thermal_attr *trip_temp_attrs;
 191        struct thermal_attr *trip_type_attrs;
 192        struct thermal_attr *trip_hyst_attrs;
 193        void *devdata;
 194        int trips;
 195        unsigned long trips_disabled;   /* bitmap for disabled trips */
 196        int passive_delay;
 197        int polling_delay;
 198        int temperature;
 199        int last_temperature;
 200        int emul_temperature;
 201        int passive;
 202        unsigned int forced_passive;
 203        atomic_t need_update;
 204        struct thermal_zone_device_ops *ops;
 205        struct thermal_zone_params *tzp;
 206        struct thermal_governor *governor;
 207        void *governor_data;
 208        struct list_head thermal_instances;
 209        struct idr idr;
 210        struct mutex lock;
 211        struct list_head node;
 212        struct delayed_work poll_queue;
 213};
 214
 215/**
 216 * struct thermal_governor - structure that holds thermal governor information
 217 * @name:       name of the governor
 218 * @bind_to_tz: callback called when binding to a thermal zone.  If it
 219 *              returns 0, the governor is bound to the thermal zone,
 220 *              otherwise it fails.
 221 * @unbind_from_tz:     callback called when a governor is unbound from a
 222 *                      thermal zone.
 223 * @throttle:   callback called for every trip point even if temperature is
 224 *              below the trip point temperature
 225 * @governor_list:      node in thermal_governor_list (in thermal_core.c)
 226 */
 227struct thermal_governor {
 228        char name[THERMAL_NAME_LENGTH];
 229        int (*bind_to_tz)(struct thermal_zone_device *tz);
 230        void (*unbind_from_tz)(struct thermal_zone_device *tz);
 231        int (*throttle)(struct thermal_zone_device *tz, int trip);
 232        struct list_head        governor_list;
 233};
 234
 235/* Structure that holds binding parameters for a zone */
 236struct thermal_bind_params {
 237        struct thermal_cooling_device *cdev;
 238
 239        /*
 240         * This is a measure of 'how effectively these devices can
 241         * cool 'this' thermal zone. It shall be determined by
 242         * platform characterization. This value is relative to the
 243         * rest of the weights so a cooling device whose weight is
 244         * double that of another cooling device is twice as
 245         * effective. See Documentation/thermal/sysfs-api.txt for more
 246         * information.
 247         */
 248        int weight;
 249
 250        /*
 251         * This is a bit mask that gives the binding relation between this
 252         * thermal zone and cdev, for a particular trip point.
 253         * See Documentation/thermal/sysfs-api.txt for more information.
 254         */
 255        int trip_mask;
 256
 257        /*
 258         * This is an array of cooling state limits. Must have exactly
 259         * 2 * thermal_zone.number_of_trip_points. It is an array consisting
 260         * of tuples <lower-state upper-state> of state limits. Each trip
 261         * will be associated with one state limit tuple when binding.
 262         * A NULL pointer means <THERMAL_NO_LIMITS THERMAL_NO_LIMITS>
 263         * on all trips.
 264         */
 265        unsigned long *binding_limits;
 266        int (*match) (struct thermal_zone_device *tz,
 267                        struct thermal_cooling_device *cdev);
 268};
 269
 270/* Structure to define Thermal Zone parameters */
 271struct thermal_zone_params {
 272        char governor_name[THERMAL_NAME_LENGTH];
 273
 274        /*
 275         * a boolean to indicate if the thermal to hwmon sysfs interface
 276         * is required. when no_hwmon == false, a hwmon sysfs interface
 277         * will be created. when no_hwmon == true, nothing will be done
 278         */
 279        bool no_hwmon;
 280
 281        int num_tbps;   /* Number of tbp entries */
 282        struct thermal_bind_params *tbp;
 283
 284        /*
 285         * Sustainable power (heat) that this thermal zone can dissipate in
 286         * mW
 287         */
 288        u32 sustainable_power;
 289
 290        /*
 291         * Proportional parameter of the PID controller when
 292         * overshooting (i.e., when temperature is below the target)
 293         */
 294        s32 k_po;
 295
 296        /*
 297         * Proportional parameter of the PID controller when
 298         * undershooting
 299         */
 300        s32 k_pu;
 301
 302        /* Integral parameter of the PID controller */
 303        s32 k_i;
 304
 305        /* Derivative parameter of the PID controller */
 306        s32 k_d;
 307
 308        /* threshold below which the error is no longer accumulated */
 309        s32 integral_cutoff;
 310
 311        /*
 312         * @slope:      slope of a linear temperature adjustment curve.
 313         *              Used by thermal zone drivers.
 314         */
 315        int slope;
 316        /*
 317         * @offset:     offset of a linear temperature adjustment curve.
 318         *              Used by thermal zone drivers (default 0).
 319         */
 320        int offset;
 321};
 322
 323struct thermal_genl_event {
 324        u32 orig;
 325        enum events event;
 326};
 327
 328/**
 329 * struct thermal_zone_of_device_ops - scallbacks for handling DT based zones
 330 *
 331 * Mandatory:
 332 * @get_temp: a pointer to a function that reads the sensor temperature.
 333 *
 334 * Optional:
 335 * @get_trend: a pointer to a function that reads the sensor temperature trend.
 336 * @set_emul_temp: a pointer to a function that sets sensor emulated
 337 *                 temperature.
 338 */
 339struct thermal_zone_of_device_ops {
 340        int (*get_temp)(void *, int *);
 341        int (*get_trend)(void *, long *);
 342        int (*set_emul_temp)(void *, int);
 343};
 344
 345/**
 346 * struct thermal_trip - representation of a point in temperature domain
 347 * @np: pointer to struct device_node that this trip point was created from
 348 * @temperature: temperature value in miliCelsius
 349 * @hysteresis: relative hysteresis in miliCelsius
 350 * @type: trip point type
 351 */
 352
 353struct thermal_trip {
 354        struct device_node *np;
 355        int temperature;
 356        int hysteresis;
 357        enum thermal_trip_type type;
 358};
 359
 360/* Function declarations */
 361#ifdef CONFIG_THERMAL_OF
 362struct thermal_zone_device *
 363thermal_zone_of_sensor_register(struct device *dev, int id, void *data,
 364                                const struct thermal_zone_of_device_ops *ops);
 365void thermal_zone_of_sensor_unregister(struct device *dev,
 366                                       struct thermal_zone_device *tz);
 367struct thermal_zone_device *devm_thermal_zone_of_sensor_register(
 368                struct device *dev, int id, void *data,
 369                const struct thermal_zone_of_device_ops *ops);
 370void devm_thermal_zone_of_sensor_unregister(struct device *dev,
 371                                            struct thermal_zone_device *tz);
 372#else
 373static inline struct thermal_zone_device *
 374thermal_zone_of_sensor_register(struct device *dev, int id, void *data,
 375                                const struct thermal_zone_of_device_ops *ops)
 376{
 377        return ERR_PTR(-ENODEV);
 378}
 379
 380static inline
 381void thermal_zone_of_sensor_unregister(struct device *dev,
 382                                       struct thermal_zone_device *tz)
 383{
 384}
 385
 386static inline struct thermal_zone_device *devm_thermal_zone_of_sensor_register(
 387                struct device *dev, int id, void *data,
 388                const struct thermal_zone_of_device_ops *ops)
 389{
 390        return ERR_PTR(-ENODEV);
 391}
 392
 393static inline
 394void devm_thermal_zone_of_sensor_unregister(struct device *dev,
 395                                            struct thermal_zone_device *tz)
 396{
 397}
 398
 399#endif
 400
 401#if IS_ENABLED(CONFIG_THERMAL)
 402static inline bool cdev_is_power_actor(struct thermal_cooling_device *cdev)
 403{
 404        return cdev->ops->get_requested_power && cdev->ops->state2power &&
 405                cdev->ops->power2state;
 406}
 407
 408int power_actor_get_max_power(struct thermal_cooling_device *,
 409                              struct thermal_zone_device *tz, u32 *max_power);
 410int power_actor_get_min_power(struct thermal_cooling_device *,
 411                              struct thermal_zone_device *tz, u32 *min_power);
 412int power_actor_set_power(struct thermal_cooling_device *,
 413                          struct thermal_instance *, u32);
 414struct thermal_zone_device *thermal_zone_device_register(const char *, int, int,
 415                void *, struct thermal_zone_device_ops *,
 416                struct thermal_zone_params *, int, int);
 417void thermal_zone_device_unregister(struct thermal_zone_device *);
 418
 419int thermal_zone_bind_cooling_device(struct thermal_zone_device *, int,
 420                                     struct thermal_cooling_device *,
 421                                     unsigned long, unsigned long,
 422                                     unsigned int);
 423int thermal_zone_unbind_cooling_device(struct thermal_zone_device *, int,
 424                                       struct thermal_cooling_device *);
 425void thermal_zone_device_update(struct thermal_zone_device *);
 426
 427struct thermal_cooling_device *thermal_cooling_device_register(char *, void *,
 428                const struct thermal_cooling_device_ops *);
 429struct thermal_cooling_device *
 430thermal_of_cooling_device_register(struct device_node *np, char *, void *,
 431                                   const struct thermal_cooling_device_ops *);
 432void thermal_cooling_device_unregister(struct thermal_cooling_device *);
 433struct thermal_zone_device *thermal_zone_get_zone_by_name(const char *name);
 434int thermal_zone_get_temp(struct thermal_zone_device *tz, int *temp);
 435
 436int get_tz_trend(struct thermal_zone_device *, int);
 437struct thermal_instance *get_thermal_instance(struct thermal_zone_device *,
 438                struct thermal_cooling_device *, int);
 439void thermal_cdev_update(struct thermal_cooling_device *);
 440void thermal_notify_framework(struct thermal_zone_device *, int);
 441#else
 442static inline bool cdev_is_power_actor(struct thermal_cooling_device *cdev)
 443{ return false; }
 444static inline int power_actor_get_max_power(struct thermal_cooling_device *cdev,
 445                              struct thermal_zone_device *tz, u32 *max_power)
 446{ return 0; }
 447static inline int power_actor_get_min_power(struct thermal_cooling_device *cdev,
 448                                            struct thermal_zone_device *tz,
 449                                            u32 *min_power)
 450{ return -ENODEV; }
 451static inline int power_actor_set_power(struct thermal_cooling_device *cdev,
 452                          struct thermal_instance *tz, u32 power)
 453{ return 0; }
 454static inline struct thermal_zone_device *thermal_zone_device_register(
 455        const char *type, int trips, int mask, void *devdata,
 456        struct thermal_zone_device_ops *ops,
 457        const struct thermal_zone_params *tzp,
 458        int passive_delay, int polling_delay)
 459{ return ERR_PTR(-ENODEV); }
 460static inline void thermal_zone_device_unregister(
 461        struct thermal_zone_device *tz)
 462{ }
 463static inline int thermal_zone_bind_cooling_device(
 464        struct thermal_zone_device *tz, int trip,
 465        struct thermal_cooling_device *cdev,
 466        unsigned long upper, unsigned long lower,
 467        unsigned int weight)
 468{ return -ENODEV; }
 469static inline int thermal_zone_unbind_cooling_device(
 470        struct thermal_zone_device *tz, int trip,
 471        struct thermal_cooling_device *cdev)
 472{ return -ENODEV; }
 473static inline void thermal_zone_device_update(struct thermal_zone_device *tz)
 474{ }
 475static inline struct thermal_cooling_device *
 476thermal_cooling_device_register(char *type, void *devdata,
 477        const struct thermal_cooling_device_ops *ops)
 478{ return ERR_PTR(-ENODEV); }
 479static inline struct thermal_cooling_device *
 480thermal_of_cooling_device_register(struct device_node *np,
 481        char *type, void *devdata, const struct thermal_cooling_device_ops *ops)
 482{ return ERR_PTR(-ENODEV); }
 483static inline void thermal_cooling_device_unregister(
 484        struct thermal_cooling_device *cdev)
 485{ }
 486static inline struct thermal_zone_device *thermal_zone_get_zone_by_name(
 487                const char *name)
 488{ return ERR_PTR(-ENODEV); }
 489static inline int thermal_zone_get_temp(
 490                struct thermal_zone_device *tz, int *temp)
 491{ return -ENODEV; }
 492static inline int get_tz_trend(struct thermal_zone_device *tz, int trip)
 493{ return -ENODEV; }
 494static inline struct thermal_instance *
 495get_thermal_instance(struct thermal_zone_device *tz,
 496        struct thermal_cooling_device *cdev, int trip)
 497{ return ERR_PTR(-ENODEV); }
 498static inline void thermal_cdev_update(struct thermal_cooling_device *cdev)
 499{ }
 500static inline void thermal_notify_framework(struct thermal_zone_device *tz,
 501        int trip)
 502{ }
 503#endif /* CONFIG_THERMAL */
 504
 505#if defined(CONFIG_NET) && IS_ENABLED(CONFIG_THERMAL)
 506extern int thermal_generate_netlink_event(struct thermal_zone_device *tz,
 507                                                enum events event);
 508#else
 509static inline int thermal_generate_netlink_event(struct thermal_zone_device *tz,
 510                                                enum events event)
 511{
 512        return 0;
 513}
 514#endif
 515
 516#endif /* __THERMAL_H__ */
 517