driver-api/thermal/sysfs-api.rst

2 Generic Thermal Sysfs driver How To
13 The generic thermal sysfs provides a set of interfaces for thermal zone
14 devices (sensors) and thermal cooling devices (fan, processor...) to register
15 with the thermal management solution and to be a part of it.
17 This how-to focuses on enabling new thermal zone and cooling devices to
18 participate in thermal management.
19 This solution is platform independent and any type of thermal zone devices
22 The main task of the thermal sysfs driver is to expose thermal zone attributes
24 An intelligent thermal management application can make decisions based on
25 inputs from thermal zone attributes (the current temperature and trip point
31 1. thermal sysfs driver interface functions
34 1.1 thermal zone device interface
48     This interface function adds a new thermal zone device (sensor) to the
49     /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the
50     thermal cooling devices registered to it at the same time.
53 	the thermal zone type.
55 	the table of trip points for this thermal zone.
59 	thermal zone device call-backs.
63 		a given trip point in this thermal zone.
65 		get the current temperature of the thermal zone.
71 		change the mode (enabled/disabled) of the thermal zone.
75 		get the critical temperature for this thermal zone.
86 	thermal zone platform parameters.
98     This interface function removes the thermal zone device.
99     It deletes the corresponding entry from /sys/class/thermal folder and
100     unbinds all the thermal cooling devices it uses.
109 	This interface adds a new sensor to a DT thermal zone.
110 	This function will search the list of thermal zones described in
114 	thermal zone device.
136 					left the driver must inform the thermal
144 	The thermal zone temperature is provided by the get_temp() function
148 	It returns error pointer if fails otherwise valid thermal zone device
157 	This interface unregisters a sensor from a DT thermal zone which was
160 	thermal zone device registered with thermal_zone_of_sensor_register()
162 	get_trend() thermal zone device callbacks.
200 	for the thermal zone device, which might be useful for platform
208 	for the thermal zone device, which might be useful for platform
211 1.2 thermal cooling device interface
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 itself
223     to all the thermal zone devices registered at the same time.
230 	thermal cooling devices call-backs.
244     This interface function removes the thermal cooling device.
245     It deletes the corresponding entry from /sys/class/thermal folder and
246     unbinds itself from all the thermal zone devices using it.
248 1.4 Thermal Zone Parameters
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.
261 	       Name of the thermal governor used for this zone
263 	       a boolean to indicate if the thermal to hwmon sysfs interface
278 Thermal sysfs attributes will be represented under /sys/class/thermal.
282 Thermal zone device sys I/F, created once it's registered::
284   /sys/class/thermal/thermal_zone[0-*]:
285     |---type:			Type of the thermal zone
287     |---mode:			Working mode of the thermal zone
288     |---policy:			Thermal governor used for this zone
289     |---available_policies:	Available thermal governors for this zone
303 Thermal cooling device sys I/F, created once it's registered::
305   /sys/class/thermal/cooling_device[0-*]:
317 the relationship between a thermal zone and its associated cooling device.
321   /sys/class/thermal/thermal_zone[0-*]:
322     |---cdev[0-*]:		[0-*]th cooling device in current thermal zone
325 				this thermal zone
327 Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
328 the generic thermal driver also creates a hwmon sysfs I/F for each _type_
329 of thermal zone device. E.g. the generic thermal driver registers one hwmon
331 ACPI thermal zones.
333 Please read Documentation/ABI/testing/sysfs-class-thermal for thermal
339     |---name:			The type of the thermal zone devices
340     |---temp[1-*]_input:	The current temperature of thermal zone [1-*]
341     |---temp[1-*]_critical:	The critical trip point of thermal zone [1-*]
348 ACPI thermal zone may support multiple trip points like critical, hot,
349 passive, active. If an ACPI thermal zone supports critical, passive,
354 effectiveness in cooling the thermal zone.
359  /sys/class/thermal:
374     |---cdev0:			--->/sys/class/thermal/cooling_device0
377     |---cdev1:			--->/sys/class/thermal/cooling_device3
403 This function returns the trend of a thermal zone, i.e the rate of change
404 of temperature of the thermal zone. Ideally, the thermal sensor drivers
405 are supposed to implement the callback. If they don't, the thermal
419 On an event of critical trip temperature crossing the thermal framework