431 lines · plain
1===================================2Generic Thermal Sysfs driver How To3===================================4 5Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>6 7Copyright (c) 2008 Intel Corporation8 9 100. Introduction11===============12 13The generic thermal sysfs provides a set of interfaces for thermal zone14devices (sensors) and thermal cooling devices (fan, processor...) to register15with the thermal management solution and to be a part of it.16 17This how-to focuses on enabling new thermal zone and cooling devices to18participate in thermal management.19This solution is platform independent and any type of thermal zone devices20and cooling devices should be able to make use of the infrastructure.21 22The main task of the thermal sysfs driver is to expose thermal zone attributes23as well as cooling device attributes to the user space.24An intelligent thermal management application can make decisions based on25inputs from thermal zone attributes (the current temperature and trip point26temperature) and throttle appropriate devices.27 28- `[0-*]` denotes any positive number starting from 029- `[1-*]` denotes any positive number starting from 130 311. thermal sysfs driver interface functions32===========================================33 341.1 thermal zone device interface35---------------------------------36 37 ::38 39 struct thermal_zone_device *40 thermal_zone_device_register_with_trips(const char *type,41 const struct thermal_trip *trips,42 int num_trips, void *devdata,43 const struct thermal_zone_device_ops *ops,44 const struct thermal_zone_params *tzp,45 unsigned int passive_delay,46 unsigned int polling_delay)47 48 This interface function adds a new thermal zone device (sensor) to the49 /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the50 thermal cooling devices registered to it at the same time.51 52 type:53 the thermal zone type.54 trips:55 the table of trip points for this thermal zone.56 devdata:57 device private data58 ops:59 thermal zone device call-backs.60 61 .should_bind:62 check whether or not a given cooling device should be bound to63 a given trip point in this thermal zone.64 .get_temp:65 get the current temperature of the thermal zone.66 .set_trips:67 set the trip points window. Whenever the current temperature68 is updated, the trip points immediately below and above the69 current temperature are found.70 .change_mode:71 change the mode (enabled/disabled) of the thermal zone.72 .set_trip_temp:73 set the temperature of a given trip point.74 .get_crit_temp:75 get the critical temperature for this thermal zone.76 .set_emul_temp:77 set the emulation temperature which helps in debugging78 different threshold temperature points.79 .get_trend:80 get the trend of most recent zone temperature changes.81 .hot:82 hot trip point crossing handler.83 .critical:84 critical trip point crossing handler.85 tzp:86 thermal zone platform parameters.87 passive_delay:88 number of milliseconds to wait between polls when performing passive89 cooling.90 polling_delay:91 number of milliseconds to wait between polls when checking92 whether trip points have been crossed (0 for interrupt driven systems).93 94 ::95 96 void thermal_zone_device_unregister(struct thermal_zone_device *tz)97 98 This interface function removes the thermal zone device.99 It deletes the corresponding entry from /sys/class/thermal folder and100 unbinds all the thermal cooling devices it uses.101 102 ::103 104 struct thermal_zone_device105 *thermal_zone_of_sensor_register(struct device *dev, int sensor_id,106 void *data,107 const struct thermal_zone_of_device_ops *ops)108 109 This interface adds a new sensor to a DT thermal zone.110 This function will search the list of thermal zones described in111 device tree and look for the zone that refer to the sensor device112 pointed by dev->of_node as temperature providers. For the zone113 pointing to the sensor node, the sensor will be added to the DT114 thermal zone device.115 116 The parameters for this interface are:117 118 dev:119 Device node of sensor containing valid node pointer in120 dev->of_node.121 sensor_id:122 a sensor identifier, in case the sensor IP has more123 than one sensors124 data:125 a private pointer (owned by the caller) that will be126 passed back, when a temperature reading is needed.127 ops:128 `struct thermal_zone_of_device_ops *`.129 130 ============== =======================================131 get_temp a pointer to a function that reads the132 sensor temperature. This is mandatory133 callback provided by sensor driver.134 set_trips a pointer to a function that sets a135 temperature window. When this window is136 left the driver must inform the thermal137 core via thermal_zone_device_update.138 get_trend a pointer to a function that reads the139 sensor temperature trend.140 set_emul_temp a pointer to a function that sets141 sensor emulated temperature.142 ============== =======================================143 144 The thermal zone temperature is provided by the get_temp() function145 pointer of thermal_zone_of_device_ops. When called, it will146 have the private pointer @data back.147 148 It returns error pointer if fails otherwise valid thermal zone device149 handle. Caller should check the return handle with IS_ERR() for finding150 whether success or not.151 152 ::153 154 void thermal_zone_of_sensor_unregister(struct device *dev,155 struct thermal_zone_device *tzd)156 157 This interface unregisters a sensor from a DT thermal zone which was158 successfully added by interface thermal_zone_of_sensor_register().159 This function removes the sensor callbacks and private data from the160 thermal zone device registered with thermal_zone_of_sensor_register()161 interface. It will also silent the zone by remove the .get_temp() and162 get_trend() thermal zone device callbacks.163 164 ::165 166 struct thermal_zone_device167 *devm_thermal_zone_of_sensor_register(struct device *dev,168 int sensor_id,169 void *data,170 const struct thermal_zone_of_device_ops *ops)171 172 This interface is resource managed version of173 thermal_zone_of_sensor_register().174 175 All details of thermal_zone_of_sensor_register() described in176 section 1.1.3 is applicable here.177 178 The benefit of using this interface to register sensor is that it179 is not require to explicitly call thermal_zone_of_sensor_unregister()180 in error path or during driver unbinding as this is done by driver181 resource manager.182 183 ::184 185 void devm_thermal_zone_of_sensor_unregister(struct device *dev,186 struct thermal_zone_device *tzd)187 188 This interface is resource managed version of189 thermal_zone_of_sensor_unregister().190 All details of thermal_zone_of_sensor_unregister() described in191 section 1.1.4 is applicable here.192 Normally this function will not need to be called and the resource193 management code will ensure that the resource is freed.194 195 ::196 197 int thermal_zone_get_slope(struct thermal_zone_device *tz)198 199 This interface is used to read the slope attribute value200 for the thermal zone device, which might be useful for platform201 drivers for temperature calculations.202 203 ::204 205 int thermal_zone_get_offset(struct thermal_zone_device *tz)206 207 This interface is used to read the offset attribute value208 for the thermal zone device, which might be useful for platform209 drivers for temperature calculations.210 2111.2 thermal cooling device interface212------------------------------------213 214 215 ::216 217 struct thermal_cooling_device218 *thermal_cooling_device_register(char *name,219 void *devdata, struct thermal_cooling_device_ops *)220 221 This interface function adds a new thermal cooling device (fan/processor/...)222 to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself223 to all the thermal zone devices registered at the same time.224 225 name:226 the cooling device name.227 devdata:228 device private data.229 ops:230 thermal cooling devices call-backs.231 232 .get_max_state:233 get the Maximum throttle state of the cooling device.234 .get_cur_state:235 get the Currently requested throttle state of the236 cooling device.237 .set_cur_state:238 set the Current throttle state of the cooling device.239 240 ::241 242 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)243 244 This interface function removes the thermal cooling device.245 It deletes the corresponding entry from /sys/class/thermal folder and246 unbinds itself from all the thermal zone devices using it.247 2481.4 Thermal Zone Parameters249---------------------------250 251 ::252 253 struct thermal_zone_params254 255 This structure defines the platform level parameters for a thermal zone.256 This data, for each thermal zone should come from the platform layer.257 This is an optional feature where some platforms can choose not to258 provide this data.259 260 .governor_name:261 Name of the thermal governor used for this zone262 .no_hwmon:263 a boolean to indicate if the thermal to hwmon sysfs interface264 is required. when no_hwmon == false, a hwmon sysfs interface265 will be created. when no_hwmon == true, nothing will be done.266 In case the thermal_zone_params is NULL, the hwmon interface267 will be created (for backward compatibility).268 2692. sysfs attributes structure270=============================271 272== ================273RO read only value274WO write only value275RW read/write value276== ================277 278Thermal sysfs attributes will be represented under /sys/class/thermal.279Hwmon sysfs I/F extension is also available under /sys/class/hwmon280if hwmon is compiled in or built as a module.281 282Thermal zone device sys I/F, created once it's registered::283 284 /sys/class/thermal/thermal_zone[0-*]:285 |---type: Type of the thermal zone286 |---temp: Current temperature287 |---mode: Working mode of the thermal zone288 |---policy: Thermal governor used for this zone289 |---available_policies: Available thermal governors for this zone290 |---trip_point_[0-*]_temp: Trip point temperature291 |---trip_point_[0-*]_type: Trip point type292 |---trip_point_[0-*]_hyst: Hysteresis value for this trip point293 |---emul_temp: Emulated temperature set node294 |---sustainable_power: Sustainable dissipatable power295 |---k_po: Proportional term during temperature overshoot296 |---k_pu: Proportional term during temperature undershoot297 |---k_i: PID's integral term in the power allocator gov298 |---k_d: PID's derivative term in the power allocator299 |---integral_cutoff: Offset above which errors are accumulated300 |---slope: Slope constant applied as linear extrapolation301 |---offset: Offset constant applied as linear extrapolation302 303Thermal cooling device sys I/F, created once it's registered::304 305 /sys/class/thermal/cooling_device[0-*]:306 |---type: Type of the cooling device(processor/fan/...)307 |---max_state: Maximum cooling state of the cooling device308 |---cur_state: Current cooling state of the cooling device309 |---stats: Directory containing cooling device's statistics310 |---stats/reset: Writing any value resets the statistics311 |---stats/time_in_state_ms: Time (msec) spent in various cooling states312 |---stats/total_trans: Total number of times cooling state is changed313 |---stats/trans_table: Cooling state transition table314 315 316Then next two dynamic attributes are created/removed in pairs. They represent317the relationship between a thermal zone and its associated cooling device.318 319::320 321 /sys/class/thermal/thermal_zone[0-*]:322 |---cdev[0-*]: [0-*]th cooling device in current thermal zone323 |---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with324 |---cdev[0-*]_weight: Influence of the cooling device in325 this thermal zone326 327Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,328the generic thermal driver also creates a hwmon sysfs I/F for each _type_329of thermal zone device. E.g. the generic thermal driver registers one hwmon330class device and build the associated hwmon sysfs I/F for all the registered331ACPI thermal zones.332 333Please read Documentation/ABI/testing/sysfs-class-thermal for thermal334zone and cooling device attribute details.335 336::337 338 /sys/class/hwmon/hwmon[0-*]:339 |---name: The type of the thermal zone devices340 |---temp[1-*]_input: The current temperature of thermal zone [1-*]341 |---temp[1-*]_critical: The critical trip point of thermal zone [1-*]342 343Please read Documentation/hwmon/sysfs-interface.rst for additional information.344 3453. A simple implementation346==========================347 348ACPI thermal zone may support multiple trip points like critical, hot,349passive, active. If an ACPI thermal zone supports critical, passive,350active[0] and active[1] at the same time, it may register itself as a351thermal_zone_device (thermal_zone1) with 4 trip points in all.352It has one processor and one fan, which are both registered as353thermal_cooling_device. Both are considered to have the same354effectiveness in cooling the thermal zone.355 356If the processor is listed in _PSL method, and the fan is listed in _AL0357method, the sys I/F structure will be built like this::358 359 /sys/class/thermal:360 |thermal_zone1:361 |---type: acpitz362 |---temp: 37000363 |---mode: enabled364 |---policy: step_wise365 |---available_policies: step_wise fair_share366 |---trip_point_0_temp: 100000367 |---trip_point_0_type: critical368 |---trip_point_1_temp: 80000369 |---trip_point_1_type: passive370 |---trip_point_2_temp: 70000371 |---trip_point_2_type: active0372 |---trip_point_3_temp: 60000373 |---trip_point_3_type: active1374 |---cdev0: --->/sys/class/thermal/cooling_device0375 |---cdev0_trip_point: 1 /* cdev0 can be used for passive */376 |---cdev0_weight: 1024377 |---cdev1: --->/sys/class/thermal/cooling_device3378 |---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/379 |---cdev1_weight: 1024380 381 |cooling_device0:382 |---type: Processor383 |---max_state: 8384 |---cur_state: 0385 386 |cooling_device3:387 |---type: Fan388 |---max_state: 2389 |---cur_state: 0390 391 /sys/class/hwmon:392 |hwmon0:393 |---name: acpitz394 |---temp1_input: 37000395 |---temp1_crit: 100000396 3974. Export Symbol APIs398=====================399 4004.1. get_tz_trend401-----------------402 403This function returns the trend of a thermal zone, i.e the rate of change404of temperature of the thermal zone. Ideally, the thermal sensor drivers405are supposed to implement the callback. If they don't, the thermal406framework calculated the trend by comparing the previous and the current407temperature values.408 4094.2. thermal_cdev_update410------------------------411 412This function serves as an arbitrator to set the state of a cooling413device. It sets the cooling device to the deepest cooling state if414possible.415 4165. thermal_emergency_poweroff417=============================418 419On an event of critical trip temperature crossing the thermal framework420shuts down the system by calling hw_protection_shutdown(). The421hw_protection_shutdown() first attempts to perform an orderly shutdown422but accepts a delay after which it proceeds doing a forced power-off423or as last resort an emergency_restart.424 425The delay should be carefully profiled so as to give adequate time for426orderly poweroff.427 428If the delay is set to 0 emergency poweroff will not be supported. So a429carefully profiled non-zero positive value is a must for emergency430poweroff to be triggered.431