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 * @passive_delay:      number of milliseconds to wait between polls when
 160 *                      performing passive cooling.
 161 * @polling_delay:      number of milliseconds to wait between polls when
 162 *                      checking whether trip points have been crossed (0 for
 163 *                      interrupt driven systems)
 164 * @temperature:        current temperature.  This is only for core code,
 165 *                      drivers should use thermal_zone_get_temp() to get the
 166 *                      current temperature
 167 * @last_temperature:   previous temperature read
 168 * @emul_temperature:   emulated temperature when using CONFIG_THERMAL_EMULATION
 169 * @passive:            1 if you've crossed a passive trip point, 0 otherwise.
 170 * @forced_passive:     If > 0, temperature at which to switch on all ACPI
 171 *                      processor cooling devices.  Currently only used by the
 172 *                      step-wise governor.
 173 * @need_update:        if equals 1, thermal_zone_device_update needs to be invoked.
 174 * @ops:        operations this &thermal_zone_device supports
 175 * @tzp:        thermal zone parameters
 176 * @governor:   pointer to the governor for this thermal zone
 177 * @governor_data:      private pointer for governor data
 178 * @thermal_instances:  list of &struct thermal_instance of this thermal zone
 179 * @idr:        &struct idr to generate unique id for this zone's cooling
 180 *              devices
 181 * @lock:       lock to protect thermal_instances list
 182 * @node:       node in thermal_tz_list (in thermal_core.c)
 183 * @poll_queue: delayed work for polling
 184 */
 185struct thermal_zone_device {
 186        int id;
 187        char type[THERMAL_NAME_LENGTH];
 188        struct device device;
 189        struct thermal_attr *trip_temp_attrs;
 190        struct thermal_attr *trip_type_attrs;
 191        struct thermal_attr *trip_hyst_attrs;
 192        void *devdata;
 193        int trips;
 194        int passive_delay;
 195        int polling_delay;
 196        int temperature;
 197        int last_temperature;
 198        int emul_temperature;
 199        int passive;
 200        unsigned int forced_passive;
 201        atomic_t need_update;
 202        struct thermal_zone_device_ops *ops;
 203        struct thermal_zone_params *tzp;
 204        struct thermal_governor *governor;
 205        void *governor_data;
 206        struct list_head thermal_instances;
 207        struct idr idr;
 208        struct mutex lock;
 209        struct list_head node;
 210        struct delayed_work poll_queue;
 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/thermal/sysfs-api.txt 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/thermal/sysfs-api.txt 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_emul_temp: a pointer to a function that sets sensor emulated
 335 *                 temperature.
 336 */
 337struct thermal_zone_of_device_ops {
 338        int (*get_temp)(void *, int *);
 339        int (*get_trend)(void *, long *);
 340        int (*set_emul_temp)(void *, int);
 341};
 342
 343/**
 344 * struct thermal_trip - representation of a point in temperature domain
 345 * @np: pointer to struct device_node that this trip point was created from
 346 * @temperature: temperature value in miliCelsius
 347 * @hysteresis: relative hysteresis in miliCelsius
 348 * @type: trip point type
 349 */
 350
 351struct thermal_trip {
 352        struct device_node *np;
 353        unsigned long int temperature;
 354        unsigned long int hysteresis;
 355        enum thermal_trip_type type;
 356};
 357
 358/* Function declarations */
 359#ifdef CONFIG_THERMAL_OF
 360struct thermal_zone_device *
 361thermal_zone_of_sensor_register(struct device *dev, int id, void *data,
 362                                const struct thermal_zone_of_device_ops *ops);
 363void thermal_zone_of_sensor_unregister(struct device *dev,
 364                                       struct thermal_zone_device *tz);
 365#else
 366static inline struct thermal_zone_device *
 367thermal_zone_of_sensor_register(struct device *dev, int id, void *data,
 368                                const struct thermal_zone_of_device_ops *ops)
 369{
 370        return ERR_PTR(-ENODEV);
 371}
 372
 373static inline
 374void thermal_zone_of_sensor_unregister(struct device *dev,
 375                                       struct thermal_zone_device *tz)
 376{
 377}
 378
 379#endif
 380
 381#if IS_ENABLED(CONFIG_THERMAL)
 382static inline bool cdev_is_power_actor(struct thermal_cooling_device *cdev)
 383{
 384        return cdev->ops->get_requested_power && cdev->ops->state2power &&
 385                cdev->ops->power2state;
 386}
 387
 388int power_actor_get_max_power(struct thermal_cooling_device *,
 389                              struct thermal_zone_device *tz, u32 *max_power);
 390int power_actor_get_min_power(struct thermal_cooling_device *,
 391                              struct thermal_zone_device *tz, u32 *min_power);
 392int power_actor_set_power(struct thermal_cooling_device *,
 393                          struct thermal_instance *, u32);
 394struct thermal_zone_device *thermal_zone_device_register(const char *, int, int,
 395                void *, struct thermal_zone_device_ops *,
 396                struct thermal_zone_params *, int, int);
 397void thermal_zone_device_unregister(struct thermal_zone_device *);
 398
 399int thermal_zone_bind_cooling_device(struct thermal_zone_device *, int,
 400                                     struct thermal_cooling_device *,
 401                                     unsigned long, unsigned long,
 402                                     unsigned int);
 403int thermal_zone_unbind_cooling_device(struct thermal_zone_device *, int,
 404                                       struct thermal_cooling_device *);
 405void thermal_zone_device_update(struct thermal_zone_device *);
 406
 407struct thermal_cooling_device *thermal_cooling_device_register(char *, void *,
 408                const struct thermal_cooling_device_ops *);
 409struct thermal_cooling_device *
 410thermal_of_cooling_device_register(struct device_node *np, char *, void *,
 411                                   const struct thermal_cooling_device_ops *);
 412void thermal_cooling_device_unregister(struct thermal_cooling_device *);
 413struct thermal_zone_device *thermal_zone_get_zone_by_name(const char *name);
 414int thermal_zone_get_temp(struct thermal_zone_device *tz, int *temp);
 415
 416int get_tz_trend(struct thermal_zone_device *, int);
 417struct thermal_instance *get_thermal_instance(struct thermal_zone_device *,
 418                struct thermal_cooling_device *, int);
 419void thermal_cdev_update(struct thermal_cooling_device *);
 420void thermal_notify_framework(struct thermal_zone_device *, int);
 421#else
 422static inline bool cdev_is_power_actor(struct thermal_cooling_device *cdev)
 423{ return false; }
 424static inline int power_actor_get_max_power(struct thermal_cooling_device *cdev,
 425                              struct thermal_zone_device *tz, u32 *max_power)
 426{ return 0; }
 427static inline int power_actor_get_min_power(struct thermal_cooling_device *cdev,
 428                                            struct thermal_zone_device *tz,
 429                                            u32 *min_power)
 430{ return -ENODEV; }
 431static inline int power_actor_set_power(struct thermal_cooling_device *cdev,
 432                          struct thermal_instance *tz, u32 power)
 433{ return 0; }
 434static inline struct thermal_zone_device *thermal_zone_device_register(
 435        const char *type, int trips, int mask, void *devdata,
 436        struct thermal_zone_device_ops *ops,
 437        const struct thermal_zone_params *tzp,
 438        int passive_delay, int polling_delay)
 439{ return ERR_PTR(-ENODEV); }
 440static inline void thermal_zone_device_unregister(
 441        struct thermal_zone_device *tz)
 442{ }
 443static inline int thermal_zone_bind_cooling_device(
 444        struct thermal_zone_device *tz, int trip,
 445        struct thermal_cooling_device *cdev,
 446        unsigned long upper, unsigned long lower,
 447        unsigned int weight)
 448{ return -ENODEV; }
 449static inline int thermal_zone_unbind_cooling_device(
 450        struct thermal_zone_device *tz, int trip,
 451        struct thermal_cooling_device *cdev)
 452{ return -ENODEV; }
 453static inline void thermal_zone_device_update(struct thermal_zone_device *tz)
 454{ }
 455static inline struct thermal_cooling_device *
 456thermal_cooling_device_register(char *type, void *devdata,
 457        const struct thermal_cooling_device_ops *ops)
 458{ return ERR_PTR(-ENODEV); }
 459static inline struct thermal_cooling_device *
 460thermal_of_cooling_device_register(struct device_node *np,
 461        char *type, void *devdata, const struct thermal_cooling_device_ops *ops)
 462{ return ERR_PTR(-ENODEV); }
 463static inline void thermal_cooling_device_unregister(
 464        struct thermal_cooling_device *cdev)
 465{ }
 466static inline struct thermal_zone_device *thermal_zone_get_zone_by_name(
 467                const char *name)
 468{ return ERR_PTR(-ENODEV); }
 469static inline int thermal_zone_get_temp(
 470                struct thermal_zone_device *tz, int *temp)
 471{ return -ENODEV; }
 472static inline int get_tz_trend(struct thermal_zone_device *tz, int trip)
 473{ return -ENODEV; }
 474static inline struct thermal_instance *
 475get_thermal_instance(struct thermal_zone_device *tz,
 476        struct thermal_cooling_device *cdev, int trip)
 477{ return ERR_PTR(-ENODEV); }
 478static inline void thermal_cdev_update(struct thermal_cooling_device *cdev)
 479{ }
 480static inline void thermal_notify_framework(struct thermal_zone_device *tz,
 481        int trip)
 482{ }
 483#endif /* CONFIG_THERMAL */
 484
 485#if defined(CONFIG_NET) && IS_ENABLED(CONFIG_THERMAL)
 486extern int thermal_generate_netlink_event(struct thermal_zone_device *tz,
 487                                                enum events event);
 488#else
 489static inline int thermal_generate_netlink_event(struct thermal_zone_device *tz,
 490                                                enum events event)
 491{
 492        return 0;
 493}
 494#endif
 495
 496#endif /* __THERMAL_H__ */
 497