1eaf7b460SMauro Carvalho Chehab=================================== 2eaf7b460SMauro Carvalho ChehabGeneric Thermal Sysfs driver How To 3eaf7b460SMauro Carvalho Chehab=================================== 4eaf7b460SMauro Carvalho Chehab 5eaf7b460SMauro Carvalho ChehabWritten by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> 6eaf7b460SMauro Carvalho Chehab 7eaf7b460SMauro Carvalho ChehabCopyright (c) 2008 Intel Corporation 8eaf7b460SMauro Carvalho Chehab 9eaf7b460SMauro Carvalho Chehab 10eaf7b460SMauro Carvalho Chehab0. Introduction 11eaf7b460SMauro Carvalho Chehab=============== 12eaf7b460SMauro Carvalho Chehab 13eaf7b460SMauro Carvalho ChehabThe generic thermal sysfs provides a set of interfaces for thermal zone 14eaf7b460SMauro Carvalho Chehabdevices (sensors) and thermal cooling devices (fan, processor...) to register 15eaf7b460SMauro Carvalho Chehabwith the thermal management solution and to be a part of it. 16eaf7b460SMauro Carvalho Chehab 17eaf7b460SMauro Carvalho ChehabThis how-to focuses on enabling new thermal zone and cooling devices to 18eaf7b460SMauro Carvalho Chehabparticipate in thermal management. 19eaf7b460SMauro Carvalho ChehabThis solution is platform independent and any type of thermal zone devices 20eaf7b460SMauro Carvalho Chehaband cooling devices should be able to make use of the infrastructure. 21eaf7b460SMauro Carvalho Chehab 22eaf7b460SMauro Carvalho ChehabThe main task of the thermal sysfs driver is to expose thermal zone attributes 23eaf7b460SMauro Carvalho Chehabas well as cooling device attributes to the user space. 24eaf7b460SMauro Carvalho ChehabAn intelligent thermal management application can make decisions based on 25eaf7b460SMauro Carvalho Chehabinputs from thermal zone attributes (the current temperature and trip point 26eaf7b460SMauro Carvalho Chehabtemperature) and throttle appropriate devices. 27eaf7b460SMauro Carvalho Chehab 28eaf7b460SMauro Carvalho Chehab- `[0-*]` denotes any positive number starting from 0 29eaf7b460SMauro Carvalho Chehab- `[1-*]` denotes any positive number starting from 1 30eaf7b460SMauro Carvalho Chehab 31eaf7b460SMauro Carvalho Chehab1. thermal sysfs driver interface functions 32eaf7b460SMauro Carvalho Chehab=========================================== 33eaf7b460SMauro Carvalho Chehab 34eaf7b460SMauro Carvalho Chehab1.1 thermal zone device interface 35eaf7b460SMauro Carvalho Chehab--------------------------------- 36eaf7b460SMauro Carvalho Chehab 37eaf7b460SMauro Carvalho Chehab :: 38eaf7b460SMauro Carvalho Chehab 39a0907422SRafael J. Wysocki struct thermal_zone_device * 40a0907422SRafael J. Wysocki thermal_zone_device_register_with_trips(const char *type, 41a0907422SRafael J. Wysocki const struct thermal_trip *trips, 42a0907422SRafael J. Wysocki int num_trips, void *devdata, 43a0907422SRafael J. Wysocki const struct thermal_zone_device_ops *ops, 44eaf7b460SMauro Carvalho Chehab const struct thermal_zone_params *tzp, 45a0907422SRafael J. Wysocki unsigned int passive_delay, 46a0907422SRafael J. Wysocki unsigned int polling_delay) 47eaf7b460SMauro Carvalho Chehab 48a0907422SRafael J. Wysocki This interface function adds a new thermal zone device (sensor) to the 49eaf7b460SMauro Carvalho Chehab /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the 50a0907422SRafael J. Wysocki thermal cooling devices registered to it at the same time. 51eaf7b460SMauro Carvalho Chehab 52eaf7b460SMauro Carvalho Chehab type: 53eaf7b460SMauro Carvalho Chehab the thermal zone type. 54eaf7b460SMauro Carvalho Chehab trips: 55a0907422SRafael J. Wysocki the table of trip points for this thermal zone. 56eaf7b460SMauro Carvalho Chehab devdata: 57eaf7b460SMauro Carvalho Chehab device private data 58eaf7b460SMauro Carvalho Chehab ops: 59eaf7b460SMauro Carvalho Chehab thermal zone device call-backs. 60eaf7b460SMauro Carvalho Chehab 61*c579286aSRafael J. Wysocki .should_bind: 62*c579286aSRafael J. Wysocki check whether or not a given cooling device should be bound to 63*c579286aSRafael J. Wysocki a given trip point in this thermal zone. 64eaf7b460SMauro Carvalho Chehab .get_temp: 65eaf7b460SMauro Carvalho Chehab get the current temperature of the thermal zone. 66eaf7b460SMauro Carvalho Chehab .set_trips: 67eaf7b460SMauro Carvalho Chehab set the trip points window. Whenever the current temperature 68eaf7b460SMauro Carvalho Chehab is updated, the trip points immediately below and above the 69eaf7b460SMauro Carvalho Chehab current temperature are found. 70a0907422SRafael J. Wysocki .change_mode: 71a0907422SRafael J. Wysocki change the mode (enabled/disabled) of the thermal zone. 72a0907422SRafael J. Wysocki .set_trip_temp: 73a0907422SRafael J. Wysocki set the temperature of a given trip point. 74a0907422SRafael J. Wysocki .get_crit_temp: 75a0907422SRafael J. Wysocki get the critical temperature for this thermal zone. 76eaf7b460SMauro Carvalho Chehab .set_emul_temp: 77eaf7b460SMauro Carvalho Chehab set the emulation temperature which helps in debugging 78eaf7b460SMauro Carvalho Chehab different threshold temperature points. 79a0907422SRafael J. Wysocki .get_trend: 80a0907422SRafael J. Wysocki get the trend of most recent zone temperature changes. 81a0907422SRafael J. Wysocki .hot: 82a0907422SRafael J. Wysocki hot trip point crossing handler. 83a0907422SRafael J. Wysocki .critical: 84a0907422SRafael J. Wysocki critical trip point crossing handler. 85eaf7b460SMauro Carvalho Chehab tzp: 86eaf7b460SMauro Carvalho Chehab thermal zone platform parameters. 87eaf7b460SMauro Carvalho Chehab passive_delay: 88a0907422SRafael J. Wysocki number of milliseconds to wait between polls when performing passive 89a0907422SRafael J. Wysocki cooling. 90eaf7b460SMauro Carvalho Chehab polling_delay: 91eaf7b460SMauro Carvalho Chehab number of milliseconds to wait between polls when checking 92eaf7b460SMauro Carvalho Chehab whether trip points have been crossed (0 for interrupt driven systems). 93eaf7b460SMauro Carvalho Chehab 94eaf7b460SMauro Carvalho Chehab :: 95eaf7b460SMauro Carvalho Chehab 96eaf7b460SMauro Carvalho Chehab void thermal_zone_device_unregister(struct thermal_zone_device *tz) 97eaf7b460SMauro Carvalho Chehab 98eaf7b460SMauro Carvalho Chehab This interface function removes the thermal zone device. 99eaf7b460SMauro Carvalho Chehab It deletes the corresponding entry from /sys/class/thermal folder and 100eaf7b460SMauro Carvalho Chehab unbinds all the thermal cooling devices it uses. 101eaf7b460SMauro Carvalho Chehab 102eaf7b460SMauro Carvalho Chehab :: 103eaf7b460SMauro Carvalho Chehab 104eaf7b460SMauro Carvalho Chehab struct thermal_zone_device 105eaf7b460SMauro Carvalho Chehab *thermal_zone_of_sensor_register(struct device *dev, int sensor_id, 106eaf7b460SMauro Carvalho Chehab void *data, 107eaf7b460SMauro Carvalho Chehab const struct thermal_zone_of_device_ops *ops) 108eaf7b460SMauro Carvalho Chehab 109eaf7b460SMauro Carvalho Chehab This interface adds a new sensor to a DT thermal zone. 110eaf7b460SMauro Carvalho Chehab This function will search the list of thermal zones described in 111eaf7b460SMauro Carvalho Chehab device tree and look for the zone that refer to the sensor device 112eaf7b460SMauro Carvalho Chehab pointed by dev->of_node as temperature providers. For the zone 113eaf7b460SMauro Carvalho Chehab pointing to the sensor node, the sensor will be added to the DT 114eaf7b460SMauro Carvalho Chehab thermal zone device. 115eaf7b460SMauro Carvalho Chehab 116eaf7b460SMauro Carvalho Chehab The parameters for this interface are: 117eaf7b460SMauro Carvalho Chehab 118eaf7b460SMauro Carvalho Chehab dev: 119eaf7b460SMauro Carvalho Chehab Device node of sensor containing valid node pointer in 120eaf7b460SMauro Carvalho Chehab dev->of_node. 121eaf7b460SMauro Carvalho Chehab sensor_id: 122eaf7b460SMauro Carvalho Chehab a sensor identifier, in case the sensor IP has more 123eaf7b460SMauro Carvalho Chehab than one sensors 124eaf7b460SMauro Carvalho Chehab data: 125eaf7b460SMauro Carvalho Chehab a private pointer (owned by the caller) that will be 126eaf7b460SMauro Carvalho Chehab passed back, when a temperature reading is needed. 127eaf7b460SMauro Carvalho Chehab ops: 128eaf7b460SMauro Carvalho Chehab `struct thermal_zone_of_device_ops *`. 129eaf7b460SMauro Carvalho Chehab 130eaf7b460SMauro Carvalho Chehab ============== ======================================= 131eaf7b460SMauro Carvalho Chehab get_temp a pointer to a function that reads the 132eaf7b460SMauro Carvalho Chehab sensor temperature. This is mandatory 133eaf7b460SMauro Carvalho Chehab callback provided by sensor driver. 134eaf7b460SMauro Carvalho Chehab set_trips a pointer to a function that sets a 135eaf7b460SMauro Carvalho Chehab temperature window. When this window is 136eaf7b460SMauro Carvalho Chehab left the driver must inform the thermal 137eaf7b460SMauro Carvalho Chehab core via thermal_zone_device_update. 138eaf7b460SMauro Carvalho Chehab get_trend a pointer to a function that reads the 139eaf7b460SMauro Carvalho Chehab sensor temperature trend. 140eaf7b460SMauro Carvalho Chehab set_emul_temp a pointer to a function that sets 141eaf7b460SMauro Carvalho Chehab sensor emulated temperature. 142eaf7b460SMauro Carvalho Chehab ============== ======================================= 143eaf7b460SMauro Carvalho Chehab 144eaf7b460SMauro Carvalho Chehab The thermal zone temperature is provided by the get_temp() function 145eaf7b460SMauro Carvalho Chehab pointer of thermal_zone_of_device_ops. When called, it will 146eaf7b460SMauro Carvalho Chehab have the private pointer @data back. 147eaf7b460SMauro Carvalho Chehab 148eaf7b460SMauro Carvalho Chehab It returns error pointer if fails otherwise valid thermal zone device 149eaf7b460SMauro Carvalho Chehab handle. Caller should check the return handle with IS_ERR() for finding 150eaf7b460SMauro Carvalho Chehab whether success or not. 151eaf7b460SMauro Carvalho Chehab 152eaf7b460SMauro Carvalho Chehab :: 153eaf7b460SMauro Carvalho Chehab 154eaf7b460SMauro Carvalho Chehab void thermal_zone_of_sensor_unregister(struct device *dev, 155eaf7b460SMauro Carvalho Chehab struct thermal_zone_device *tzd) 156eaf7b460SMauro Carvalho Chehab 157eaf7b460SMauro Carvalho Chehab This interface unregisters a sensor from a DT thermal zone which was 158eaf7b460SMauro Carvalho Chehab successfully added by interface thermal_zone_of_sensor_register(). 159eaf7b460SMauro Carvalho Chehab This function removes the sensor callbacks and private data from the 160eaf7b460SMauro Carvalho Chehab thermal zone device registered with thermal_zone_of_sensor_register() 161eaf7b460SMauro Carvalho Chehab interface. It will also silent the zone by remove the .get_temp() and 162eaf7b460SMauro Carvalho Chehab get_trend() thermal zone device callbacks. 163eaf7b460SMauro Carvalho Chehab 164eaf7b460SMauro Carvalho Chehab :: 165eaf7b460SMauro Carvalho Chehab 166eaf7b460SMauro Carvalho Chehab struct thermal_zone_device 167eaf7b460SMauro Carvalho Chehab *devm_thermal_zone_of_sensor_register(struct device *dev, 168eaf7b460SMauro Carvalho Chehab int sensor_id, 169eaf7b460SMauro Carvalho Chehab void *data, 170eaf7b460SMauro Carvalho Chehab const struct thermal_zone_of_device_ops *ops) 171eaf7b460SMauro Carvalho Chehab 172eaf7b460SMauro Carvalho Chehab This interface is resource managed version of 173eaf7b460SMauro Carvalho Chehab thermal_zone_of_sensor_register(). 174eaf7b460SMauro Carvalho Chehab 175eaf7b460SMauro Carvalho Chehab All details of thermal_zone_of_sensor_register() described in 176eaf7b460SMauro Carvalho Chehab section 1.1.3 is applicable here. 177eaf7b460SMauro Carvalho Chehab 178eaf7b460SMauro Carvalho Chehab The benefit of using this interface to register sensor is that it 179eaf7b460SMauro Carvalho Chehab is not require to explicitly call thermal_zone_of_sensor_unregister() 180eaf7b460SMauro Carvalho Chehab in error path or during driver unbinding as this is done by driver 181eaf7b460SMauro Carvalho Chehab resource manager. 182eaf7b460SMauro Carvalho Chehab 183eaf7b460SMauro Carvalho Chehab :: 184eaf7b460SMauro Carvalho Chehab 185eaf7b460SMauro Carvalho Chehab void devm_thermal_zone_of_sensor_unregister(struct device *dev, 186eaf7b460SMauro Carvalho Chehab struct thermal_zone_device *tzd) 187eaf7b460SMauro Carvalho Chehab 188eaf7b460SMauro Carvalho Chehab This interface is resource managed version of 189eaf7b460SMauro Carvalho Chehab thermal_zone_of_sensor_unregister(). 190eaf7b460SMauro Carvalho Chehab All details of thermal_zone_of_sensor_unregister() described in 191eaf7b460SMauro Carvalho Chehab section 1.1.4 is applicable here. 192eaf7b460SMauro Carvalho Chehab Normally this function will not need to be called and the resource 193eaf7b460SMauro Carvalho Chehab management code will ensure that the resource is freed. 194eaf7b460SMauro Carvalho Chehab 195eaf7b460SMauro Carvalho Chehab :: 196eaf7b460SMauro Carvalho Chehab 197eaf7b460SMauro Carvalho Chehab int thermal_zone_get_slope(struct thermal_zone_device *tz) 198eaf7b460SMauro Carvalho Chehab 199eaf7b460SMauro Carvalho Chehab This interface is used to read the slope attribute value 200eaf7b460SMauro Carvalho Chehab for the thermal zone device, which might be useful for platform 201eaf7b460SMauro Carvalho Chehab drivers for temperature calculations. 202eaf7b460SMauro Carvalho Chehab 203eaf7b460SMauro Carvalho Chehab :: 204eaf7b460SMauro Carvalho Chehab 205eaf7b460SMauro Carvalho Chehab int thermal_zone_get_offset(struct thermal_zone_device *tz) 206eaf7b460SMauro Carvalho Chehab 207eaf7b460SMauro Carvalho Chehab This interface is used to read the offset attribute value 208eaf7b460SMauro Carvalho Chehab for the thermal zone device, which might be useful for platform 209eaf7b460SMauro Carvalho Chehab drivers for temperature calculations. 210eaf7b460SMauro Carvalho Chehab 211eaf7b460SMauro Carvalho Chehab1.2 thermal cooling device interface 212eaf7b460SMauro Carvalho Chehab------------------------------------ 213eaf7b460SMauro Carvalho Chehab 214eaf7b460SMauro Carvalho Chehab 215eaf7b460SMauro Carvalho Chehab :: 216eaf7b460SMauro Carvalho Chehab 217eaf7b460SMauro Carvalho Chehab struct thermal_cooling_device 218eaf7b460SMauro Carvalho Chehab *thermal_cooling_device_register(char *name, 219eaf7b460SMauro Carvalho Chehab void *devdata, struct thermal_cooling_device_ops *) 220eaf7b460SMauro Carvalho Chehab 221eaf7b460SMauro Carvalho Chehab This interface function adds a new thermal cooling device (fan/processor/...) 222eaf7b460SMauro Carvalho Chehab to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself 223eaf7b460SMauro Carvalho Chehab to all the thermal zone devices registered at the same time. 224eaf7b460SMauro Carvalho Chehab 225eaf7b460SMauro Carvalho Chehab name: 226eaf7b460SMauro Carvalho Chehab the cooling device name. 227eaf7b460SMauro Carvalho Chehab devdata: 228eaf7b460SMauro Carvalho Chehab device private data. 229eaf7b460SMauro Carvalho Chehab ops: 230eaf7b460SMauro Carvalho Chehab thermal cooling devices call-backs. 231eaf7b460SMauro Carvalho Chehab 232eaf7b460SMauro Carvalho Chehab .get_max_state: 233eaf7b460SMauro Carvalho Chehab get the Maximum throttle state of the cooling device. 234eaf7b460SMauro Carvalho Chehab .get_cur_state: 235eaf7b460SMauro Carvalho Chehab get the Currently requested throttle state of the 236eaf7b460SMauro Carvalho Chehab cooling device. 237eaf7b460SMauro Carvalho Chehab .set_cur_state: 238eaf7b460SMauro Carvalho Chehab set the Current throttle state of the cooling device. 239eaf7b460SMauro Carvalho Chehab 240eaf7b460SMauro Carvalho Chehab :: 241eaf7b460SMauro Carvalho Chehab 242eaf7b460SMauro Carvalho Chehab void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev) 243eaf7b460SMauro Carvalho Chehab 244eaf7b460SMauro Carvalho Chehab This interface function removes the thermal cooling device. 245eaf7b460SMauro Carvalho Chehab It deletes the corresponding entry from /sys/class/thermal folder and 246eaf7b460SMauro Carvalho Chehab unbinds itself from all the thermal zone devices using it. 247eaf7b460SMauro Carvalho Chehab 248eaf7b460SMauro Carvalho Chehab1.4 Thermal Zone Parameters 249eaf7b460SMauro Carvalho Chehab--------------------------- 250eaf7b460SMauro Carvalho Chehab 251eaf7b460SMauro Carvalho Chehab :: 252eaf7b460SMauro Carvalho Chehab 253eaf7b460SMauro Carvalho Chehab struct thermal_zone_params 254eaf7b460SMauro Carvalho Chehab 255eaf7b460SMauro Carvalho Chehab This structure defines the platform level parameters for a thermal zone. 256eaf7b460SMauro Carvalho Chehab This data, for each thermal zone should come from the platform layer. 257eaf7b460SMauro Carvalho Chehab This is an optional feature where some platforms can choose not to 258eaf7b460SMauro Carvalho Chehab provide this data. 259eaf7b460SMauro Carvalho Chehab 260eaf7b460SMauro Carvalho Chehab .governor_name: 261eaf7b460SMauro Carvalho Chehab Name of the thermal governor used for this zone 262eaf7b460SMauro Carvalho Chehab .no_hwmon: 263eaf7b460SMauro Carvalho Chehab a boolean to indicate if the thermal to hwmon sysfs interface 264eaf7b460SMauro Carvalho Chehab is required. when no_hwmon == false, a hwmon sysfs interface 265eaf7b460SMauro Carvalho Chehab will be created. when no_hwmon == true, nothing will be done. 266eaf7b460SMauro Carvalho Chehab In case the thermal_zone_params is NULL, the hwmon interface 267eaf7b460SMauro Carvalho Chehab will be created (for backward compatibility). 268eaf7b460SMauro Carvalho Chehab 269eaf7b460SMauro Carvalho Chehab2. sysfs attributes structure 270eaf7b460SMauro Carvalho Chehab============================= 271eaf7b460SMauro Carvalho Chehab 272eaf7b460SMauro Carvalho Chehab== ================ 273eaf7b460SMauro Carvalho ChehabRO read only value 274eaf7b460SMauro Carvalho ChehabWO write only value 275eaf7b460SMauro Carvalho ChehabRW read/write value 276eaf7b460SMauro Carvalho Chehab== ================ 277eaf7b460SMauro Carvalho Chehab 278eaf7b460SMauro Carvalho ChehabThermal sysfs attributes will be represented under /sys/class/thermal. 279eaf7b460SMauro Carvalho ChehabHwmon sysfs I/F extension is also available under /sys/class/hwmon 280eaf7b460SMauro Carvalho Chehabif hwmon is compiled in or built as a module. 281eaf7b460SMauro Carvalho Chehab 282eaf7b460SMauro Carvalho ChehabThermal zone device sys I/F, created once it's registered:: 283eaf7b460SMauro Carvalho Chehab 284eaf7b460SMauro Carvalho Chehab /sys/class/thermal/thermal_zone[0-*]: 285eaf7b460SMauro Carvalho Chehab |---type: Type of the thermal zone 286eaf7b460SMauro Carvalho Chehab |---temp: Current temperature 287eaf7b460SMauro Carvalho Chehab |---mode: Working mode of the thermal zone 288eaf7b460SMauro Carvalho Chehab |---policy: Thermal governor used for this zone 289eaf7b460SMauro Carvalho Chehab |---available_policies: Available thermal governors for this zone 290eaf7b460SMauro Carvalho Chehab |---trip_point_[0-*]_temp: Trip point temperature 291eaf7b460SMauro Carvalho Chehab |---trip_point_[0-*]_type: Trip point type 292eaf7b460SMauro Carvalho Chehab |---trip_point_[0-*]_hyst: Hysteresis value for this trip point 293eaf7b460SMauro Carvalho Chehab |---emul_temp: Emulated temperature set node 294eaf7b460SMauro Carvalho Chehab |---sustainable_power: Sustainable dissipatable power 295eaf7b460SMauro Carvalho Chehab |---k_po: Proportional term during temperature overshoot 296eaf7b460SMauro Carvalho Chehab |---k_pu: Proportional term during temperature undershoot 297eaf7b460SMauro Carvalho Chehab |---k_i: PID's integral term in the power allocator gov 298eaf7b460SMauro Carvalho Chehab |---k_d: PID's derivative term in the power allocator 299eaf7b460SMauro Carvalho Chehab |---integral_cutoff: Offset above which errors are accumulated 300eaf7b460SMauro Carvalho Chehab |---slope: Slope constant applied as linear extrapolation 301eaf7b460SMauro Carvalho Chehab |---offset: Offset constant applied as linear extrapolation 302eaf7b460SMauro Carvalho Chehab 303eaf7b460SMauro Carvalho ChehabThermal cooling device sys I/F, created once it's registered:: 304eaf7b460SMauro Carvalho Chehab 305eaf7b460SMauro Carvalho Chehab /sys/class/thermal/cooling_device[0-*]: 306eaf7b460SMauro Carvalho Chehab |---type: Type of the cooling device(processor/fan/...) 307eaf7b460SMauro Carvalho Chehab |---max_state: Maximum cooling state of the cooling device 308eaf7b460SMauro Carvalho Chehab |---cur_state: Current cooling state of the cooling device 309eaf7b460SMauro Carvalho Chehab |---stats: Directory containing cooling device's statistics 310eaf7b460SMauro Carvalho Chehab |---stats/reset: Writing any value resets the statistics 311eaf7b460SMauro Carvalho Chehab |---stats/time_in_state_ms: Time (msec) spent in various cooling states 312eaf7b460SMauro Carvalho Chehab |---stats/total_trans: Total number of times cooling state is changed 3138fa4e938SFlavio Suligoi |---stats/trans_table: Cooling state transition table 314eaf7b460SMauro Carvalho Chehab 315eaf7b460SMauro Carvalho Chehab 316eaf7b460SMauro Carvalho ChehabThen next two dynamic attributes are created/removed in pairs. They represent 317eaf7b460SMauro Carvalho Chehabthe relationship between a thermal zone and its associated cooling device. 318eaf7b460SMauro Carvalho Chehab 319eaf7b460SMauro Carvalho Chehab:: 320eaf7b460SMauro Carvalho Chehab 321eaf7b460SMauro Carvalho Chehab /sys/class/thermal/thermal_zone[0-*]: 322eaf7b460SMauro Carvalho Chehab |---cdev[0-*]: [0-*]th cooling device in current thermal zone 323eaf7b460SMauro Carvalho Chehab |---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with 324eaf7b460SMauro Carvalho Chehab |---cdev[0-*]_weight: Influence of the cooling device in 325eaf7b460SMauro Carvalho Chehab this thermal zone 326eaf7b460SMauro Carvalho Chehab 327eaf7b460SMauro Carvalho ChehabBesides the thermal zone device sysfs I/F and cooling device sysfs I/F, 328eaf7b460SMauro Carvalho Chehabthe generic thermal driver also creates a hwmon sysfs I/F for each _type_ 329eaf7b460SMauro Carvalho Chehabof thermal zone device. E.g. the generic thermal driver registers one hwmon 330eaf7b460SMauro Carvalho Chehabclass device and build the associated hwmon sysfs I/F for all the registered 331eaf7b460SMauro Carvalho ChehabACPI thermal zones. 332eaf7b460SMauro Carvalho Chehab 33380da1b50SMauro Carvalho ChehabPlease read Documentation/ABI/testing/sysfs-class-thermal for thermal 33480da1b50SMauro Carvalho Chehabzone and cooling device attribute details. 33580da1b50SMauro Carvalho Chehab 336eaf7b460SMauro Carvalho Chehab:: 337eaf7b460SMauro Carvalho Chehab 338eaf7b460SMauro Carvalho Chehab /sys/class/hwmon/hwmon[0-*]: 339eaf7b460SMauro Carvalho Chehab |---name: The type of the thermal zone devices 340eaf7b460SMauro Carvalho Chehab |---temp[1-*]_input: The current temperature of thermal zone [1-*] 341eaf7b460SMauro Carvalho Chehab |---temp[1-*]_critical: The critical trip point of thermal zone [1-*] 342eaf7b460SMauro Carvalho Chehab 343eaf7b460SMauro Carvalho ChehabPlease read Documentation/hwmon/sysfs-interface.rst for additional information. 344eaf7b460SMauro Carvalho Chehab 345eaf7b460SMauro Carvalho Chehab3. A simple implementation 346eaf7b460SMauro Carvalho Chehab========================== 347eaf7b460SMauro Carvalho Chehab 348eaf7b460SMauro Carvalho ChehabACPI thermal zone may support multiple trip points like critical, hot, 349eaf7b460SMauro Carvalho Chehabpassive, active. If an ACPI thermal zone supports critical, passive, 350eaf7b460SMauro Carvalho Chehabactive[0] and active[1] at the same time, it may register itself as a 351eaf7b460SMauro Carvalho Chehabthermal_zone_device (thermal_zone1) with 4 trip points in all. 352eaf7b460SMauro Carvalho ChehabIt has one processor and one fan, which are both registered as 353eaf7b460SMauro Carvalho Chehabthermal_cooling_device. Both are considered to have the same 354eaf7b460SMauro Carvalho Chehabeffectiveness in cooling the thermal zone. 355eaf7b460SMauro Carvalho Chehab 356eaf7b460SMauro Carvalho ChehabIf the processor is listed in _PSL method, and the fan is listed in _AL0 357eaf7b460SMauro Carvalho Chehabmethod, the sys I/F structure will be built like this:: 358eaf7b460SMauro Carvalho Chehab 359eaf7b460SMauro Carvalho Chehab /sys/class/thermal: 360eaf7b460SMauro Carvalho Chehab |thermal_zone1: 361eaf7b460SMauro Carvalho Chehab |---type: acpitz 362eaf7b460SMauro Carvalho Chehab |---temp: 37000 363eaf7b460SMauro Carvalho Chehab |---mode: enabled 364eaf7b460SMauro Carvalho Chehab |---policy: step_wise 365eaf7b460SMauro Carvalho Chehab |---available_policies: step_wise fair_share 366eaf7b460SMauro Carvalho Chehab |---trip_point_0_temp: 100000 367eaf7b460SMauro Carvalho Chehab |---trip_point_0_type: critical 368eaf7b460SMauro Carvalho Chehab |---trip_point_1_temp: 80000 369eaf7b460SMauro Carvalho Chehab |---trip_point_1_type: passive 370eaf7b460SMauro Carvalho Chehab |---trip_point_2_temp: 70000 371eaf7b460SMauro Carvalho Chehab |---trip_point_2_type: active0 372eaf7b460SMauro Carvalho Chehab |---trip_point_3_temp: 60000 373eaf7b460SMauro Carvalho Chehab |---trip_point_3_type: active1 374eaf7b460SMauro Carvalho Chehab |---cdev0: --->/sys/class/thermal/cooling_device0 375eaf7b460SMauro Carvalho Chehab |---cdev0_trip_point: 1 /* cdev0 can be used for passive */ 376eaf7b460SMauro Carvalho Chehab |---cdev0_weight: 1024 377eaf7b460SMauro Carvalho Chehab |---cdev1: --->/sys/class/thermal/cooling_device3 378eaf7b460SMauro Carvalho Chehab |---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/ 379eaf7b460SMauro Carvalho Chehab |---cdev1_weight: 1024 380eaf7b460SMauro Carvalho Chehab 381eaf7b460SMauro Carvalho Chehab |cooling_device0: 382eaf7b460SMauro Carvalho Chehab |---type: Processor 383eaf7b460SMauro Carvalho Chehab |---max_state: 8 384eaf7b460SMauro Carvalho Chehab |---cur_state: 0 385eaf7b460SMauro Carvalho Chehab 386eaf7b460SMauro Carvalho Chehab |cooling_device3: 387eaf7b460SMauro Carvalho Chehab |---type: Fan 388eaf7b460SMauro Carvalho Chehab |---max_state: 2 389eaf7b460SMauro Carvalho Chehab |---cur_state: 0 390eaf7b460SMauro Carvalho Chehab 391eaf7b460SMauro Carvalho Chehab /sys/class/hwmon: 392eaf7b460SMauro Carvalho Chehab |hwmon0: 393eaf7b460SMauro Carvalho Chehab |---name: acpitz 394eaf7b460SMauro Carvalho Chehab |---temp1_input: 37000 395eaf7b460SMauro Carvalho Chehab |---temp1_crit: 100000 396eaf7b460SMauro Carvalho Chehab 397f96c8e50SAmit Kucheria4. Export Symbol APIs 398eaf7b460SMauro Carvalho Chehab===================== 399eaf7b460SMauro Carvalho Chehab 400f96c8e50SAmit Kucheria4.1. get_tz_trend 401eaf7b460SMauro Carvalho Chehab----------------- 402eaf7b460SMauro Carvalho Chehab 403eaf7b460SMauro Carvalho ChehabThis function returns the trend of a thermal zone, i.e the rate of change 404eaf7b460SMauro Carvalho Chehabof temperature of the thermal zone. Ideally, the thermal sensor drivers 405eaf7b460SMauro Carvalho Chehabare supposed to implement the callback. If they don't, the thermal 406eaf7b460SMauro Carvalho Chehabframework calculated the trend by comparing the previous and the current 407eaf7b460SMauro Carvalho Chehabtemperature values. 408eaf7b460SMauro Carvalho Chehab 40996d81990SRafael J. Wysocki4.2. thermal_cdev_update 410eaf7b460SMauro Carvalho Chehab------------------------ 411eaf7b460SMauro Carvalho Chehab 412eaf7b460SMauro Carvalho ChehabThis function serves as an arbitrator to set the state of a cooling 413eaf7b460SMauro Carvalho Chehabdevice. It sets the cooling device to the deepest cooling state if 414eaf7b460SMauro Carvalho Chehabpossible. 415eaf7b460SMauro Carvalho Chehab 416f96c8e50SAmit Kucheria5. thermal_emergency_poweroff 417eaf7b460SMauro Carvalho Chehab============================= 418eaf7b460SMauro Carvalho Chehab 419db0aeb4fSMatti VaittinenOn an event of critical trip temperature crossing the thermal framework 420db0aeb4fSMatti Vaittinenshuts down the system by calling hw_protection_shutdown(). The 421db0aeb4fSMatti Vaittinenhw_protection_shutdown() first attempts to perform an orderly shutdown 422db0aeb4fSMatti Vaittinenbut accepts a delay after which it proceeds doing a forced power-off 423db0aeb4fSMatti Vaittinenor as last resort an emergency_restart. 424eaf7b460SMauro Carvalho Chehab 425eaf7b460SMauro Carvalho ChehabThe delay should be carefully profiled so as to give adequate time for 426db0aeb4fSMatti Vaittinenorderly poweroff. 427eaf7b460SMauro Carvalho Chehab 428db0aeb4fSMatti VaittinenIf the delay is set to 0 emergency poweroff will not be supported. So a 429db0aeb4fSMatti Vaittinencarefully profiled non-zero positive value is a must for emergency 430db0aeb4fSMatti Vaittinenpoweroff to be triggered. 431