[deliverable/linux.git] / Documentation / thermal / sysfs-api.txt

Generic Thermal Sysfs driver How To
===================================

Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>

Updated: 2 January 2008

Copyright (c)  2008 Intel Corporation


0. Introduction

The generic thermal sysfs provides a set of interfaces for thermal zone
devices (sensors) and thermal cooling devices (fan, processor...) to register
with the thermal management solution and to be a part of it.

This how-to focuses on enabling new thermal zone and cooling devices to
participate in thermal management.
This solution is platform independent and any type of thermal zone devices
and cooling devices should be able to make use of the infrastructure.

The main task of the thermal sysfs driver is to expose thermal zone attributes
as well as cooling device attributes to the user space.
An intelligent thermal management application can make decisions based on
inputs from thermal zone attributes (the current temperature and trip point
temperature) and throttle appropriate devices.

[0-*]	denotes any positive number starting from 0
[1-*]	denotes any positive number starting from 1

1. thermal sysfs driver interface functions

1.1 thermal zone device interface
1.1.1 struct thermal_zone_device *thermal_zone_device_register(char *type,
		int trips, int mask, void *devdata,
		struct thermal_zone_device_ops *ops,
		const struct thermal_zone_params *tzp,
		int passive_delay, int polling_delay))

    This interface function adds a new thermal zone device (sensor) to
    /sys/class/thermal folder as thermal_zone[0-*]. It tries to bind all the
    thermal cooling devices registered at the same time.

    type: the thermal zone type.
    trips: the total number of trip points this thermal zone supports.
    mask: Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
    devdata: device private data
    ops: thermal zone device call-backs.
	.bind: bind the thermal zone device with a thermal cooling device.
	.unbind: unbind the thermal zone device with a thermal cooling device.
	.get_temp: get the current temperature of the thermal zone.
	.get_mode: get the current mode (enabled/disabled) of the thermal zone.
	    - "enabled" means the kernel thermal management is enabled.
	    - "disabled" will prevent kernel thermal driver action upon trip points
	      so that user applications can take charge of thermal management.
	.set_mode: set the mode (enabled/disabled) of the thermal zone.
	.get_trip_type: get the type of certain trip point.
	.get_trip_temp: get the temperature above which the certain trip point
			will be fired.
	.set_emul_temp: set the emulation temperature which helps in debugging
			different threshold temperature points.
    tzp: thermal zone platform parameters.
    passive_delay: number of milliseconds to wait between polls when
	performing passive cooling.
    polling_delay: number of milliseconds to wait between polls when checking
	whether trip points have been crossed (0 for interrupt driven systems).


1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz)

    This interface function removes the thermal zone device.
    It deletes the corresponding entry form /sys/class/thermal folder and
    unbind all the thermal cooling devices it uses.

1.2 thermal cooling device interface
1.2.1 struct thermal_cooling_device *thermal_cooling_device_register(char *name,
		void *devdata, struct thermal_cooling_device_ops *)

    This interface function adds a new thermal cooling device (fan/processor/...)
    to /sys/class/thermal/ folder as cooling_device[0-*]. It tries to bind itself
    to all the thermal zone devices register at the same time.
    name: the cooling device name.
    devdata: device private data.
    ops: thermal cooling devices call-backs.
	.get_max_state: get the Maximum throttle state of the cooling device.
	.get_cur_state: get the Current throttle state of the cooling device.
	.set_cur_state: set the Current throttle state of the cooling device.

1.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)

    This interface function remove the thermal cooling device.
    It deletes the corresponding entry form /sys/class/thermal folder and
    unbind itself from all the thermal zone devices using it.

1.3 interface for binding a thermal zone device with a thermal cooling device
1.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
	int trip, struct thermal_cooling_device *cdev,
	unsigned long upper, unsigned long lower, unsigned int weight);

    This interface function bind a thermal cooling device to the certain trip
    point of a thermal zone device.
    This function is usually called in the thermal zone device .bind callback.
    tz: the thermal zone device
    cdev: thermal cooling device
    trip: indicates which trip point the cooling devices is associated with
	  in this thermal zone.
    upper:the Maximum cooling state for this trip point.
          THERMAL_NO_LIMIT means no upper limit,
	  and the cooling device can be in max_state.
    lower:the Minimum cooling state can be used for this trip point.
          THERMAL_NO_LIMIT means no lower limit,
	  and the cooling device can be in cooling state 0.
    weight: the influence of this cooling device in this thermal
            zone.  See 1.4.1 below for more information.

1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
		int trip, struct thermal_cooling_device *cdev);

    This interface function unbind a thermal cooling device from the certain
    trip point of a thermal zone device. This function is usually called in
    the thermal zone device .unbind callback.
    tz: the thermal zone device
    cdev: thermal cooling device
    trip: indicates which trip point the cooling devices is associated with
	  in this thermal zone.

1.4 Thermal Zone Parameters
1.4.1 struct thermal_bind_params
    This structure defines the following parameters that are used to bind
    a zone with a cooling device for a particular trip point.
    .cdev: The cooling device pointer
    .weight: The 'influence' of a particular cooling device on this zone.
             This is on a percentage scale. The sum of all these weights
             (for a particular zone) cannot exceed 100.
    .trip_mask:This is a bit mask that gives the binding relation between
               this thermal zone and cdev, for a particular trip point.
               If nth bit is set, then the cdev and thermal zone are bound
               for trip point n.
    .limits: This is an array of cooling state limits. Must have exactly
         2 * thermal_zone.number_of_trip_points. It is an array consisting
         of tuples <lower-state upper-state> of state limits. Each trip
         will be associated with one state limit tuple when binding.
         A NULL pointer means <THERMAL_NO_LIMITS THERMAL_NO_LIMITS>
         on all trips. These limits are used when binding a cdev to a
         trip point.
    .match: This call back returns success(0) if the 'tz and cdev' need to
	    be bound, as per platform data.
1.4.2 struct thermal_zone_params
    This structure defines the platform level parameters for a thermal zone.
    This data, for each thermal zone should come from the platform layer.
    This is an optional feature where some platforms can choose not to
    provide this data.
    .governor_name: Name of the thermal governor used for this zone
    .no_hwmon: a boolean to indicate if the thermal to hwmon sysfs interface
               is required. when no_hwmon == false, a hwmon sysfs interface
               will be created. when no_hwmon == true, nothing will be done.
               In case the thermal_zone_params is NULL, the hwmon interface
               will be created (for backward compatibility).
    .num_tbps: Number of thermal_bind_params entries for this zone
    .tbp: thermal_bind_params entries

2. sysfs attributes structure

RO	read only value
RW	read/write value

Thermal sysfs attributes will be represented under /sys/class/thermal.
Hwmon sysfs I/F extension is also available under /sys/class/hwmon
if hwmon is compiled in or built as a module.

Thermal zone device sys I/F, created once it's registered:
/sys/class/thermal/thermal_zone[0-*]:
    |---type:			Type of the thermal zone
    |---temp:			Current temperature
    |---mode:			Working mode of the thermal zone
    |---policy:			Thermal governor used for this zone
    |---trip_point_[0-*]_temp:	Trip point temperature
    |---trip_point_[0-*]_type:	Trip point type
    |---trip_point_[0-*]_hyst:	Hysteresis value for this trip point
    |---emul_temp:		Emulated temperature set node

Thermal cooling device sys I/F, created once it's registered:
/sys/class/thermal/cooling_device[0-*]:
    |---type:			Type of the cooling device(processor/fan/...)
    |---max_state:		Maximum cooling state of the cooling device
    |---cur_state:		Current cooling state of the cooling device


Then next two dynamic attributes are created/removed in pairs. They represent
the relationship between a thermal zone and its associated cooling device.
They are created/removed for each successful execution of
thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.

/sys/class/thermal/thermal_zone[0-*]:
    |---cdev[0-*]:		[0-*]th cooling device in current thermal zone
    |---cdev[0-*]_trip_point:	Trip point that cdev[0-*] is associated with
    |---cdev[0-*]_weight:       Influence of the cooling device in
                                this thermal zone

Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
the generic thermal driver also creates a hwmon sysfs I/F for each _type_
of thermal zone device. E.g. the generic thermal driver registers one hwmon
class device and build the associated hwmon sysfs I/F for all the registered
ACPI thermal zones.

/sys/class/hwmon/hwmon[0-*]:
    |---name:			The type of the thermal zone devices
    |---temp[1-*]_input:	The current temperature of thermal zone [1-*]
    |---temp[1-*]_critical:	The critical trip point of thermal zone [1-*]

Please read Documentation/hwmon/sysfs-interface for additional information.

***************************
* Thermal zone attributes *
***************************

type
	Strings which represent the thermal zone type.
	This is given by thermal zone driver as part of registration.
	E.g: "acpitz" indicates it's an ACPI thermal device.
	In order to keep it consistent with hwmon sys attribute; this should
	be a short, lowercase string, not containing spaces nor dashes.
	RO, Required

temp
	Current temperature as reported by thermal zone (sensor).
	Unit: millidegree Celsius
	RO, Required

mode
	One of the predefined values in [enabled, disabled].
	This file gives information about the algorithm that is currently
	managing the thermal zone. It can be either default kernel based
	algorithm or user space application.
	enabled		= enable Kernel Thermal management.
	disabled	= Preventing kernel thermal zone driver actions upon
			  trip points so that user application can take full
			  charge of the thermal management.
	RW, Optional

policy
	One of the various thermal governors used for a particular zone.
	RW, Required

trip_point_[0-*]_temp
	The temperature above which trip point will be fired.
	Unit: millidegree Celsius
	RO, Optional

trip_point_[0-*]_type
	Strings which indicate the type of the trip point.
	E.g. it can be one of critical, hot, passive, active[0-*] for ACPI
	thermal zone.
	RO, Optional

trip_point_[0-*]_hyst
	The hysteresis value for a trip point, represented as an integer
	Unit: Celsius
	RW, Optional

cdev[0-*]
	Sysfs link to the thermal cooling device node where the sys I/F
	for cooling device throttling control represents.
	RO, Optional

cdev[0-*]_trip_point
	The trip point with which cdev[0-*] is associated in this thermal
	zone; -1 means the cooling device is not associated with any trip
	point.
	RO, Optional

cdev[0-*]_weight
        The influence of cdev[0-*] in this thermal zone. This value
        is relative to the rest of cooling devices in the thermal
        zone. For example, if a cooling device has a weight double
        than that of other, it's twice as effective in cooling the
        thermal zone.
        RW, Optional

passive
	Attribute is only present for zones in which the passive cooling
	policy is not supported by native thermal driver. Default is zero
	and can be set to a temperature (in millidegrees) to enable a
	passive trip point for the zone. Activation is done by polling with
	an interval of 1 second.
	Unit: millidegrees Celsius
	Valid values: 0 (disabled) or greater than 1000
	RW, Optional

emul_temp
	Interface to set the emulated temperature method in thermal zone
	(sensor). After setting this temperature, the thermal zone may pass
	this temperature to platform emulation function if registered or
	cache it locally. This is useful in debugging different temperature
	threshold and its associated cooling action. This is write only node
	and writing 0 on this node should disable emulation.
	Unit: millidegree Celsius
	WO, Optional

	  WARNING: Be careful while enabling this option on production systems,
	  because userland can easily disable the thermal policy by simply
	  flooding this sysfs node with low temperature values.

*****************************
* Cooling device attributes *
*****************************

type
	String which represents the type of device, e.g:
	- for generic ACPI: should be "Fan", "Processor" or "LCD"
	- for memory controller device on intel_menlow platform:
	  should be "Memory controller".
	RO, Required

max_state
	The maximum permissible cooling state of this cooling device.
	RO, Required

cur_state
	The current cooling state of this cooling device.
	The value can any integer numbers between 0 and max_state:
	- cur_state == 0 means no cooling
	- cur_state == max_state means the maximum cooling.
	RW, Required

3. A simple implementation

ACPI thermal zone may support multiple trip points like critical, hot,
passive, active. If an ACPI thermal zone supports critical, passive,
active[0] and active[1] at the same time, it may register itself as a
thermal_zone_device (thermal_zone1) with 4 trip points in all.
It has one processor and one fan, which are both registered as
thermal_cooling_device. Both are considered to have the same
effectiveness in cooling the thermal zone.

If the processor is listed in _PSL method, and the fan is listed in _AL0
method, the sys I/F structure will be built like this:

/sys/class/thermal:

|thermal_zone1:
    |---type:			acpitz
    |---temp:			37000
    |---mode:			enabled
    |---policy:			step_wise
    |---trip_point_0_temp:	100000
    |---trip_point_0_type:	critical
    |---trip_point_1_temp:	80000
    |---trip_point_1_type:	passive
    |---trip_point_2_temp:	70000
    |---trip_point_2_type:	active0
    |---trip_point_3_temp:	60000
    |---trip_point_3_type:	active1
    |---cdev0:			--->/sys/class/thermal/cooling_device0
    |---cdev0_trip_point:	1	/* cdev0 can be used for passive */
    |---cdev0_weight:           1024
    |---cdev1:			--->/sys/class/thermal/cooling_device3
    |---cdev1_trip_point:	2	/* cdev1 can be used for active[0]*/
    |---cdev1_weight:           1024

|cooling_device0:
    |---type:			Processor
    |---max_state:		8
    |---cur_state:		0

|cooling_device3:
    |---type:			Fan
    |---max_state:		2
    |---cur_state:		0

/sys/class/hwmon:

|hwmon0:
    |---name:			acpitz
    |---temp1_input:		37000
    |---temp1_crit:		100000

4. Event Notification

The framework includes a simple notification mechanism, in the form of a
netlink event. Netlink socket initialization is done during the _init_
of the framework. Drivers which intend to use the notification mechanism
just need to call thermal_generate_netlink_event() with two arguments viz
(originator, event). The originator is a pointer to struct thermal_zone_device
from where the event has been originated. An integer which represents the
thermal zone device will be used in the message to identify the zone. The
event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
crosses any of the configured thresholds.

5. Export Symbol APIs:

5.1: get_tz_trend:
This function returns the trend of a thermal zone, i.e the rate of change
of temperature of the thermal zone. Ideally, the thermal sensor drivers
are supposed to implement the callback. If they don't, the thermal
framework calculated the trend by comparing the previous and the current
temperature values.

5.2:get_thermal_instance:
This function returns the thermal_instance corresponding to a given
{thermal_zone, cooling_device, trip_point} combination. Returns NULL
if such an instance does not exist.

5.3:thermal_notify_framework:
This function handles the trip events from sensor drivers. It starts
throttling the cooling devices according to the policy configured.
For CRITICAL and HOT trip points, this notifies the respective drivers,
and does actual throttling for other trip points i.e ACTIVE and PASSIVE.
The throttling policy is based on the configured platform data; if no
platform data is provided, this uses the step_wise throttling policy.

5.4:thermal_cdev_update:
This function serves as an arbitrator to set the state of a cooling
device. It sets the cooling device to the deepest cooling state if
possible.
Commit	Line	Data
203d3d4a	1	Generic Thermal Sysfs driver How To
38bb0849	2	===================================
203d3d4a ZR	3
	4	Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>
	5
	6	Updated: 2 January 2008
	7
	8	Copyright (c) 2008 Intel Corporation
	9
	10
	11	0. Introduction
	12
38bb0849 FP	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.
203d3d4a	16
38bb0849 FP	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
	20	and cooling devices should be able to make use of the infrastructure.
203d3d4a	21
38bb0849 FP	22	The main task of the thermal sysfs driver is to expose thermal zone attributes
	23	as well as cooling device attributes to the user space.
	24	An intelligent thermal management application can make decisions based on
	25	inputs from thermal zone attributes (the current temperature and trip point
	26	temperature) and throttle appropriate devices.
203d3d4a ZR	27
	28	[0-*] denotes any positive number starting from 0
	29	[1-*] denotes any positive number starting from 1
	30
	31	1. thermal sysfs driver interface functions
	32
	33	1.1 thermal zone device interface
514e6d20	34	1.1.1 struct thermal_zone_device thermal_zone_device_register(char type,
c56f5c03	35	int trips, int mask, void *devdata,
514e6d20 ZR	36	struct thermal_zone_device_ops *ops,
	37	const struct thermal_zone_params *tzp,
	38	int passive_delay, int polling_delay))
38bb0849 FP	39
	40	This interface function adds a new thermal zone device (sensor) to
	41	/sys/class/thermal folder as thermal_zone[0-*]. It tries to bind all the
	42	thermal cooling devices registered at the same time.
	43
514e6d20	44	type: the thermal zone type.
38bb0849	45	trips: the total number of trip points this thermal zone supports.
c56f5c03	46	mask: Bit string: If 'n'th bit is set, then trip point 'n' is writeable.
38bb0849 FP	47	devdata: device private data
	48	ops: thermal zone device call-backs.
	49	.bind: bind the thermal zone device with a thermal cooling device.
	50	.unbind: unbind the thermal zone device with a thermal cooling device.
	51	.get_temp: get the current temperature of the thermal zone.
8eaa8d6c ZR	52	.get_mode: get the current mode (enabled/disabled) of the thermal zone.
	53	- "enabled" means the kernel thermal management is enabled.
	54	- "disabled" will prevent kernel thermal driver action upon trip points
38bb0849	55	so that user applications can take charge of thermal management.
8eaa8d6c	56	.set_mode: set the mode (enabled/disabled) of the thermal zone.
38bb0849 FP	57	.get_trip_type: get the type of certain trip point.
	58	.get_trip_temp: get the temperature above which the certain trip point
	59	will be fired.
e6e238c3 ADK	60	.set_emul_temp: set the emulation temperature which helps in debugging
e6e238c3 ADK	61	different threshold temperature points.
514e6d20 ZR	62	tzp: thermal zone platform parameters.
	63	passive_delay: number of milliseconds to wait between polls when
	64	performing passive cooling.
	65	polling_delay: number of milliseconds to wait between polls when checking
	66	whether trip points have been crossed (0 for interrupt driven systems).
	67
203d3d4a ZR	68
	69	1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz)
	70
38bb0849 FP	71	This interface function removes the thermal zone device.
	72	It deletes the corresponding entry form /sys/class/thermal folder and
	73	unbind all the thermal cooling devices it uses.
203d3d4a ZR	74
	75	1.2 thermal cooling device interface
	76	1.2.1 struct thermal_cooling_device thermal_cooling_device_register(char name,
38bb0849 FP	77	void devdata, struct thermal_cooling_device_ops )
	78
	79	This interface function adds a new thermal cooling device (fan/processor/...)
	80	to /sys/class/thermal/ folder as cooling_device[0-*]. It tries to bind itself
	81	to all the thermal zone devices register at the same time.
	82	name: the cooling device name.
	83	devdata: device private data.
	84	ops: thermal cooling devices call-backs.
	85	.get_max_state: get the Maximum throttle state of the cooling device.
	86	.get_cur_state: get the Current throttle state of the cooling device.
	87	.set_cur_state: set the Current throttle state of the cooling device.
203d3d4a ZR	88
	89	1.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
	90
38bb0849 FP	91	This interface function remove the thermal cooling device.
	92	It deletes the corresponding entry form /sys/class/thermal folder and
	93	unbind itself from all the thermal zone devices using it.
203d3d4a ZR	94
	95	1.3 interface for binding a thermal zone device with a thermal cooling device
	96	1.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
9d99842f	97	int trip, struct thermal_cooling_device *cdev,
6cd9e9f6	98	unsigned long upper, unsigned long lower, unsigned int weight);
203d3d4a	99
38bb0849 FP	100	This interface function bind a thermal cooling device to the certain trip
	101	point of a thermal zone device.
	102	This function is usually called in the thermal zone device .bind callback.
	103	tz: the thermal zone device
	104	cdev: thermal cooling device
	105	trip: indicates which trip point the cooling devices is associated with
	106	in this thermal zone.
9d99842f ZR	107	upper:the Maximum cooling state for this trip point.
	108	THERMAL_NO_LIMIT means no upper limit,
	109	and the cooling device can be in max_state.
	110	lower:the Minimum cooling state can be used for this trip point.
	111	THERMAL_NO_LIMIT means no lower limit,
	112	and the cooling device can be in cooling state 0.
6cd9e9f6 KS	113	weight: the influence of this cooling device in this thermal
6cd9e9f6 KS	114	zone. See 1.4.1 below for more information.
203d3d4a ZR	115
203d3d4a ZR	116	1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
38bb0849	117	int trip, struct thermal_cooling_device *cdev);
203d3d4a	118
38bb0849 FP	119	This interface function unbind a thermal cooling device from the certain
	120	trip point of a thermal zone device. This function is usually called in
	121	the thermal zone device .unbind callback.
	122	tz: the thermal zone device
	123	cdev: thermal cooling device
	124	trip: indicates which trip point the cooling devices is associated with
	125	in this thermal zone.
203d3d4a	126
6ea083b1 D	127	1.4 Thermal Zone Parameters
	128	1.4.1 struct thermal_bind_params
	129	This structure defines the following parameters that are used to bind
	130	a zone with a cooling device for a particular trip point.
	131	.cdev: The cooling device pointer
	132	.weight: The 'influence' of a particular cooling device on this zone.
	133	This is on a percentage scale. The sum of all these weights
	134	(for a particular zone) cannot exceed 100.
	135	.trip_mask:This is a bit mask that gives the binding relation between
	136	this thermal zone and cdev, for a particular trip point.
	137	If nth bit is set, then the cdev and thermal zone are bound
	138	for trip point n.
a8892d83 EV	139	.limits: This is an array of cooling state limits. Must have exactly
	140	2 * thermal_zone.number_of_trip_points. It is an array consisting
	141	of tuples <lower-state upper-state> of state limits. Each trip
	142	will be associated with one state limit tuple when binding.
	143	A NULL pointer means <THERMAL_NO_LIMITS THERMAL_NO_LIMITS>
	144	on all trips. These limits are used when binding a cdev to a
	145	trip point.
6ea083b1 D	146	.match: This call back returns success(0) if the 'tz and cdev' need to
	147	be bound, as per platform data.
	148	1.4.2 struct thermal_zone_params
	149	This structure defines the platform level parameters for a thermal zone.
	150	This data, for each thermal zone should come from the platform layer.
	151	This is an optional feature where some platforms can choose not to
	152	provide this data.
	153	.governor_name: Name of the thermal governor used for this zone
ccba4ffd EV	154	.no_hwmon: a boolean to indicate if the thermal to hwmon sysfs interface
	155	is required. when no_hwmon == false, a hwmon sysfs interface
	156	will be created. when no_hwmon == true, nothing will be done.
	157	In case the thermal_zone_params is NULL, the hwmon interface
	158	will be created (for backward compatibility).
6ea083b1 D	159	.num_tbps: Number of thermal_bind_params entries for this zone
	160	.tbp: thermal_bind_params entries
	161
203d3d4a ZR	162	2. sysfs attributes structure
	163
	164	RO read only value
	165	RW read/write value
	166
e9ae7107 ZR	167	Thermal sysfs attributes will be represented under /sys/class/thermal.
	168	Hwmon sysfs I/F extension is also available under /sys/class/hwmon
	169	if hwmon is compiled in or built as a module.
203d3d4a ZR	170
203d3d4a ZR	171	Thermal zone device sys I/F, created once it's registered:
e9ae7107	172	/sys/class/thermal/thermal_zone[0-*]:
38bb0849 FP	173	\|---type: Type of the thermal zone
	174	\|---temp: Current temperature
	175	\|---mode: Working mode of the thermal zone
6ea083b1	176	\|---policy: Thermal governor used for this zone
38bb0849 FP	177	\|---trip_point_[0-*]_temp: Trip point temperature
38bb0849 FP	178	\|---trip_point_[0-*]_type: Trip point type
27365a6c	179	\|---trip_point_[0-*]_hyst: Hysteresis value for this trip point
e6e238c3	180	\|---emul_temp: Emulated temperature set node
203d3d4a ZR	181
203d3d4a ZR	182	Thermal cooling device sys I/F, created once it's registered:
e9ae7107	183	/sys/class/thermal/cooling_device[0-*]:
38bb0849 FP	184	\|---type: Type of the cooling device(processor/fan/...)
	185	\|---max_state: Maximum cooling state of the cooling device
	186	\|---cur_state: Current cooling state of the cooling device
203d3d4a ZR	187
203d3d4a ZR	188
38bb0849 FP	189	Then next two dynamic attributes are created/removed in pairs. They represent
	190	the relationship between a thermal zone and its associated cooling device.
	191	They are created/removed for each successful execution of
	192	thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.
203d3d4a	193
38bb0849 FP	194	/sys/class/thermal/thermal_zone[0-*]:
	195	\|---cdev[0-]: [0-]th cooling device in current thermal zone
	196	\|---cdev[0-]_trip_point: Trip point that cdev[0-] is associated with
db916513 JM	197	\|---cdev[0-*]_weight: Influence of the cooling device in
db916513 JM	198	this thermal zone
203d3d4a	199
e9ae7107	200	Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
38bb0849 FP	201	the generic thermal driver also creates a hwmon sysfs I/F for each _type_
	202	of thermal zone device. E.g. the generic thermal driver registers one hwmon
	203	class device and build the associated hwmon sysfs I/F for all the registered
	204	ACPI thermal zones.
	205
e9ae7107	206	/sys/class/hwmon/hwmon[0-*]:
38bb0849 FP	207	\|---name: The type of the thermal zone devices
	208	\|---temp[1-]_input: The current temperature of thermal zone [1-]
	209	\|---temp[1-]_critical: The critical trip point of thermal zone [1-]
	210
e9ae7107	211	Please read Documentation/hwmon/sysfs-interface for additional information.
203d3d4a ZR	212
	213	***************************
	214	* Thermal zone attributes *
	215	***************************
	216
38bb0849 FP	217	type
	218	Strings which represent the thermal zone type.
	219	This is given by thermal zone driver as part of registration.
	220	E.g: "acpitz" indicates it's an ACPI thermal device.
	221	In order to keep it consistent with hwmon sys attribute; this should
	222	be a short, lowercase string, not containing spaces nor dashes.
	223	RO, Required
	224
	225	temp
	226	Current temperature as reported by thermal zone (sensor).
	227	Unit: millidegree Celsius
	228	RO, Required
	229
	230	mode
8eaa8d6c	231	One of the predefined values in [enabled, disabled].
38bb0849 FP	232	This file gives information about the algorithm that is currently
	233	managing the thermal zone. It can be either default kernel based
	234	algorithm or user space application.
8eaa8d6c ZR	235	enabled = enable Kernel Thermal management.
	236	disabled = Preventing kernel thermal zone driver actions upon
	237	trip points so that user application can take full
	238	charge of the thermal management.
38bb0849 FP	239	RW, Optional
38bb0849 FP	240
6ea083b1 D	241	policy
	242	One of the various thermal governors used for a particular zone.
	243	RW, Required
	244
38bb0849 FP	245	trip_point_[0-*]_temp
	246	The temperature above which trip point will be fired.
	247	Unit: millidegree Celsius
	248	RO, Optional
	249
	250	trip_point_[0-*]_type
	251	Strings which indicate the type of the trip point.
	252	E.g. it can be one of critical, hot, passive, active[0-*] for ACPI
	253	thermal zone.
	254	RO, Optional
	255
27365a6c D	256	trip_point_[0-*]_hyst
	257	The hysteresis value for a trip point, represented as an integer
	258	Unit: Celsius
	259	RW, Optional
	260
38bb0849 FP	261	cdev[0-*]
	262	Sysfs link to the thermal cooling device node where the sys I/F
	263	for cooling device throttling control represents.
	264	RO, Optional
	265
	266	cdev[0-*]_trip_point
	267	The trip point with which cdev[0-*] is associated in this thermal
	268	zone; -1 means the cooling device is not associated with any trip
	269	point.
	270	RO, Optional
29226ed3	271
db916513 JM	272	cdev[0-*]_weight
	273	The influence of cdev[0-*] in this thermal zone. This value
	274	is relative to the rest of cooling devices in the thermal
	275	zone. For example, if a cooling device has a weight double
	276	than that of other, it's twice as effective in cooling the
	277	thermal zone.
	278	RW, Optional
	279
29226ed3 FP	280	passive
	281	Attribute is only present for zones in which the passive cooling
	282	policy is not supported by native thermal driver. Default is zero
	283	and can be set to a temperature (in millidegrees) to enable a
	284	passive trip point for the zone. Activation is done by polling with
	285	an interval of 1 second.
	286	Unit: millidegrees Celsius
3d8e3ad8	287	Valid values: 0 (disabled) or greater than 1000
29226ed3	288	RW, Optional
38bb0849	289
e6e238c3 ADK	290	emul_temp
	291	Interface to set the emulated temperature method in thermal zone
	292	(sensor). After setting this temperature, the thermal zone may pass
	293	this temperature to platform emulation function if registered or
	294	cache it locally. This is useful in debugging different temperature
	295	threshold and its associated cooling action. This is write only node
	296	and writing 0 on this node should disable emulation.
	297	Unit: millidegree Celsius
	298	WO, Optional
	299
8837295a EV	300	WARNING: Be careful while enabling this option on production systems,
	301	because userland can easily disable the thermal policy by simply
	302	flooding this sysfs node with low temperature values.
	303
38bb0849 FP	304	*****************************
	305	* Cooling device attributes *
	306	*****************************
	307
	308	type
	309	String which represents the type of device, e.g:
	310	- for generic ACPI: should be "Fan", "Processor" or "LCD"
	311	- for memory controller device on intel_menlow platform:
	312	should be "Memory controller".
	313	RO, Required
	314
	315	max_state
	316	The maximum permissible cooling state of this cooling device.
	317	RO, Required
	318
	319	cur_state
	320	The current cooling state of this cooling device.
	321	The value can any integer numbers between 0 and max_state:
	322	- cur_state == 0 means no cooling
	323	- cur_state == max_state means the maximum cooling.
	324	RW, Required
203d3d4a ZR	325
	326	3. A simple implementation
	327
38bb0849 FP	328	ACPI thermal zone may support multiple trip points like critical, hot,
	329	passive, active. If an ACPI thermal zone supports critical, passive,
	330	active[0] and active[1] at the same time, it may register itself as a
	331	thermal_zone_device (thermal_zone1) with 4 trip points in all.
	332	It has one processor and one fan, which are both registered as
db916513 JM	333	thermal_cooling_device. Both are considered to have the same
db916513 JM	334	effectiveness in cooling the thermal zone.
38bb0849 FP	335
	336	If the processor is listed in _PSL method, and the fan is listed in _AL0
	337	method, the sys I/F structure will be built like this:
203d3d4a ZR	338
	339	/sys/class/thermal:
	340
	341	\|thermal_zone1:
38bb0849 FP	342	\|---type: acpitz
38bb0849 FP	343	\|---temp: 37000
8eaa8d6c	344	\|---mode: enabled
6ea083b1	345	\|---policy: step_wise
38bb0849 FP	346	\|---trip_point_0_temp: 100000
	347	\|---trip_point_0_type: critical
	348	\|---trip_point_1_temp: 80000
	349	\|---trip_point_1_type: passive
	350	\|---trip_point_2_temp: 70000
	351	\|---trip_point_2_type: active0
	352	\|---trip_point_3_temp: 60000
	353	\|---trip_point_3_type: active1
	354	\|---cdev0: --->/sys/class/thermal/cooling_device0
	355	\|---cdev0_trip_point: 1 /* cdev0 can be used for passive */
db916513	356	\|---cdev0_weight: 1024
38bb0849 FP	357	\|---cdev1: --->/sys/class/thermal/cooling_device3
38bb0849 FP	358	\|---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/
db916513	359	\|---cdev1_weight: 1024
203d3d4a ZR	360
203d3d4a ZR	361	\|cooling_device0:
38bb0849 FP	362	\|---type: Processor
	363	\|---max_state: 8
	364	\|---cur_state: 0
203d3d4a ZR	365
203d3d4a ZR	366	\|cooling_device3:
38bb0849 FP	367	\|---type: Fan
	368	\|---max_state: 2
	369	\|---cur_state: 0
e9ae7107 ZR	370
	371	/sys/class/hwmon:
	372
	373	\|hwmon0:
38bb0849 FP	374	\|---name: acpitz
	375	\|---temp1_input: 37000
	376	\|---temp1_crit: 100000
4cb18728 D	377
	378	4. Event Notification
	379
	380	The framework includes a simple notification mechanism, in the form of a
	381	netlink event. Netlink socket initialization is done during the _init_
	382	of the framework. Drivers which intend to use the notification mechanism
2d58d7ea	383	just need to call thermal_generate_netlink_event() with two arguments viz
8ab3e6a0 EV	384	(originator, event). The originator is a pointer to struct thermal_zone_device
	385	from where the event has been originated. An integer which represents the
	386	thermal zone device will be used in the message to identify the zone. The
4cb18728 D	387	event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
	388	THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
	389	crosses any of the configured thresholds.
6ea083b1 D	390
	391	5. Export Symbol APIs:
	392
	393	5.1: get_tz_trend:
	394	This function returns the trend of a thermal zone, i.e the rate of change
	395	of temperature of the thermal zone. Ideally, the thermal sensor drivers
	396	are supposed to implement the callback. If they don't, the thermal
	397	framework calculated the trend by comparing the previous and the current
	398	temperature values.
	399
	400	5.2:get_thermal_instance:
	401	This function returns the thermal_instance corresponding to a given
	402	{thermal_zone, cooling_device, trip_point} combination. Returns NULL
	403	if such an instance does not exist.
	404
7b73c993	405	5.3:thermal_notify_framework:
6ea083b1 D	406	This function handles the trip events from sensor drivers. It starts
	407	throttling the cooling devices according to the policy configured.
	408	For CRITICAL and HOT trip points, this notifies the respective drivers,
	409	and does actual throttling for other trip points i.e ACTIVE and PASSIVE.
	410	The throttling policy is based on the configured platform data; if no
	411	platform data is provided, this uses the step_wise throttling policy.
	412
	413	5.4:thermal_cdev_update:
	414	This function serves as an arbitrator to set the state of a cooling
	415	device. It sets the cooling device to the deepest cooling state if
	416	possible.