[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 relative to the rest of the cooling
             devices. For example, if all cooling devices have a
             weight of 1, then they all contribute the same. You can
             use percentages if you want, but it's not mandatory. A
             weight of 0 means that this cooling device doesn't
             contribute to the cooling of this zone unless all cooling
             devices have a weight of 0. If all weights are 0, then
             they all contribute the same.
    .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
bcdcbbc7 JM	132	.weight: The 'influence' of a particular cooling device on this
	133	zone. This is relative to the rest of the cooling
	134	devices. For example, if all cooling devices have a
	135	weight of 1, then they all contribute the same. You can
	136	use percentages if you want, but it's not mandatory. A
	137	weight of 0 means that this cooling device doesn't
	138	contribute to the cooling of this zone unless all cooling
	139	devices have a weight of 0. If all weights are 0, then
	140	they all contribute the same.
6ea083b1 D	141	.trip_mask:This is a bit mask that gives the binding relation between
	142	this thermal zone and cdev, for a particular trip point.
	143	If nth bit is set, then the cdev and thermal zone are bound
	144	for trip point n.
a8892d83 EV	145	.limits: This is an array of cooling state limits. Must have exactly
	146	2 * thermal_zone.number_of_trip_points. It is an array consisting
	147	of tuples <lower-state upper-state> of state limits. Each trip
	148	will be associated with one state limit tuple when binding.
	149	A NULL pointer means <THERMAL_NO_LIMITS THERMAL_NO_LIMITS>
	150	on all trips. These limits are used when binding a cdev to a
	151	trip point.
6ea083b1 D	152	.match: This call back returns success(0) if the 'tz and cdev' need to
	153	be bound, as per platform data.
	154	1.4.2 struct thermal_zone_params
	155	This structure defines the platform level parameters for a thermal zone.
	156	This data, for each thermal zone should come from the platform layer.
	157	This is an optional feature where some platforms can choose not to
	158	provide this data.
	159	.governor_name: Name of the thermal governor used for this zone
ccba4ffd EV	160	.no_hwmon: a boolean to indicate if the thermal to hwmon sysfs interface
	161	is required. when no_hwmon == false, a hwmon sysfs interface
	162	will be created. when no_hwmon == true, nothing will be done.
	163	In case the thermal_zone_params is NULL, the hwmon interface
	164	will be created (for backward compatibility).
6ea083b1 D	165	.num_tbps: Number of thermal_bind_params entries for this zone
	166	.tbp: thermal_bind_params entries
	167
203d3d4a ZR	168	2. sysfs attributes structure
	169
	170	RO read only value
	171	RW read/write value
	172
e9ae7107 ZR	173	Thermal sysfs attributes will be represented under /sys/class/thermal.
	174	Hwmon sysfs I/F extension is also available under /sys/class/hwmon
	175	if hwmon is compiled in or built as a module.
203d3d4a ZR	176
203d3d4a ZR	177	Thermal zone device sys I/F, created once it's registered:
e9ae7107	178	/sys/class/thermal/thermal_zone[0-*]:
38bb0849 FP	179	\|---type: Type of the thermal zone
	180	\|---temp: Current temperature
	181	\|---mode: Working mode of the thermal zone
6ea083b1	182	\|---policy: Thermal governor used for this zone
38bb0849 FP	183	\|---trip_point_[0-*]_temp: Trip point temperature
38bb0849 FP	184	\|---trip_point_[0-*]_type: Trip point type
27365a6c	185	\|---trip_point_[0-*]_hyst: Hysteresis value for this trip point
e6e238c3	186	\|---emul_temp: Emulated temperature set node
203d3d4a ZR	187
203d3d4a ZR	188	Thermal cooling device sys I/F, created once it's registered:
e9ae7107	189	/sys/class/thermal/cooling_device[0-*]:
38bb0849 FP	190	\|---type: Type of the cooling device(processor/fan/...)
	191	\|---max_state: Maximum cooling state of the cooling device
	192	\|---cur_state: Current cooling state of the cooling device
203d3d4a ZR	193
203d3d4a ZR	194
38bb0849 FP	195	Then next two dynamic attributes are created/removed in pairs. They represent
	196	the relationship between a thermal zone and its associated cooling device.
	197	They are created/removed for each successful execution of
	198	thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device.
203d3d4a	199
38bb0849 FP	200	/sys/class/thermal/thermal_zone[0-*]:
	201	\|---cdev[0-]: [0-]th cooling device in current thermal zone
	202	\|---cdev[0-]_trip_point: Trip point that cdev[0-] is associated with
db916513 JM	203	\|---cdev[0-*]_weight: Influence of the cooling device in
db916513 JM	204	this thermal zone
203d3d4a	205
e9ae7107	206	Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
38bb0849 FP	207	the generic thermal driver also creates a hwmon sysfs I/F for each _type_
	208	of thermal zone device. E.g. the generic thermal driver registers one hwmon
	209	class device and build the associated hwmon sysfs I/F for all the registered
	210	ACPI thermal zones.
	211
e9ae7107	212	/sys/class/hwmon/hwmon[0-*]:
38bb0849 FP	213	\|---name: The type of the thermal zone devices
	214	\|---temp[1-]_input: The current temperature of thermal zone [1-]
	215	\|---temp[1-]_critical: The critical trip point of thermal zone [1-]
	216
e9ae7107	217	Please read Documentation/hwmon/sysfs-interface for additional information.
203d3d4a ZR	218
	219	***************************
	220	* Thermal zone attributes *
	221	***************************
	222
38bb0849 FP	223	type
	224	Strings which represent the thermal zone type.
	225	This is given by thermal zone driver as part of registration.
	226	E.g: "acpitz" indicates it's an ACPI thermal device.
	227	In order to keep it consistent with hwmon sys attribute; this should
	228	be a short, lowercase string, not containing spaces nor dashes.
	229	RO, Required
	230
	231	temp
	232	Current temperature as reported by thermal zone (sensor).
	233	Unit: millidegree Celsius
	234	RO, Required
	235
	236	mode
8eaa8d6c	237	One of the predefined values in [enabled, disabled].
38bb0849 FP	238	This file gives information about the algorithm that is currently
	239	managing the thermal zone. It can be either default kernel based
	240	algorithm or user space application.
8eaa8d6c ZR	241	enabled = enable Kernel Thermal management.
	242	disabled = Preventing kernel thermal zone driver actions upon
	243	trip points so that user application can take full
	244	charge of the thermal management.
38bb0849 FP	245	RW, Optional
38bb0849 FP	246
6ea083b1 D	247	policy
	248	One of the various thermal governors used for a particular zone.
	249	RW, Required
	250
38bb0849 FP	251	trip_point_[0-*]_temp
	252	The temperature above which trip point will be fired.
	253	Unit: millidegree Celsius
	254	RO, Optional
	255
	256	trip_point_[0-*]_type
	257	Strings which indicate the type of the trip point.
	258	E.g. it can be one of critical, hot, passive, active[0-*] for ACPI
	259	thermal zone.
	260	RO, Optional
	261
27365a6c D	262	trip_point_[0-*]_hyst
	263	The hysteresis value for a trip point, represented as an integer
	264	Unit: Celsius
	265	RW, Optional
	266
38bb0849 FP	267	cdev[0-*]
	268	Sysfs link to the thermal cooling device node where the sys I/F
	269	for cooling device throttling control represents.
	270	RO, Optional
	271
	272	cdev[0-*]_trip_point
	273	The trip point with which cdev[0-*] is associated in this thermal
	274	zone; -1 means the cooling device is not associated with any trip
	275	point.
	276	RO, Optional
29226ed3	277
db916513 JM	278	cdev[0-*]_weight
	279	The influence of cdev[0-*] in this thermal zone. This value
	280	is relative to the rest of cooling devices in the thermal
	281	zone. For example, if a cooling device has a weight double
	282	than that of other, it's twice as effective in cooling the
	283	thermal zone.
	284	RW, Optional
	285
29226ed3 FP	286	passive
	287	Attribute is only present for zones in which the passive cooling
	288	policy is not supported by native thermal driver. Default is zero
	289	and can be set to a temperature (in millidegrees) to enable a
	290	passive trip point for the zone. Activation is done by polling with
	291	an interval of 1 second.
	292	Unit: millidegrees Celsius
3d8e3ad8	293	Valid values: 0 (disabled) or greater than 1000
29226ed3	294	RW, Optional
38bb0849	295
e6e238c3 ADK	296	emul_temp
	297	Interface to set the emulated temperature method in thermal zone
	298	(sensor). After setting this temperature, the thermal zone may pass
	299	this temperature to platform emulation function if registered or
	300	cache it locally. This is useful in debugging different temperature
	301	threshold and its associated cooling action. This is write only node
	302	and writing 0 on this node should disable emulation.
	303	Unit: millidegree Celsius
	304	WO, Optional
	305
8837295a EV	306	WARNING: Be careful while enabling this option on production systems,
	307	because userland can easily disable the thermal policy by simply
	308	flooding this sysfs node with low temperature values.
	309
38bb0849 FP	310	*****************************
	311	* Cooling device attributes *
	312	*****************************
	313
	314	type
	315	String which represents the type of device, e.g:
	316	- for generic ACPI: should be "Fan", "Processor" or "LCD"
	317	- for memory controller device on intel_menlow platform:
	318	should be "Memory controller".
	319	RO, Required
	320
	321	max_state
	322	The maximum permissible cooling state of this cooling device.
	323	RO, Required
	324
	325	cur_state
	326	The current cooling state of this cooling device.
	327	The value can any integer numbers between 0 and max_state:
	328	- cur_state == 0 means no cooling
	329	- cur_state == max_state means the maximum cooling.
	330	RW, Required
203d3d4a ZR	331
	332	3. A simple implementation
	333
38bb0849 FP	334	ACPI thermal zone may support multiple trip points like critical, hot,
	335	passive, active. If an ACPI thermal zone supports critical, passive,
	336	active[0] and active[1] at the same time, it may register itself as a
	337	thermal_zone_device (thermal_zone1) with 4 trip points in all.
	338	It has one processor and one fan, which are both registered as
db916513 JM	339	thermal_cooling_device. Both are considered to have the same
db916513 JM	340	effectiveness in cooling the thermal zone.
38bb0849 FP	341
	342	If the processor is listed in _PSL method, and the fan is listed in _AL0
	343	method, the sys I/F structure will be built like this:
203d3d4a ZR	344
	345	/sys/class/thermal:
	346
	347	\|thermal_zone1:
38bb0849 FP	348	\|---type: acpitz
38bb0849 FP	349	\|---temp: 37000
8eaa8d6c	350	\|---mode: enabled
6ea083b1	351	\|---policy: step_wise
38bb0849 FP	352	\|---trip_point_0_temp: 100000
	353	\|---trip_point_0_type: critical
	354	\|---trip_point_1_temp: 80000
	355	\|---trip_point_1_type: passive
	356	\|---trip_point_2_temp: 70000
	357	\|---trip_point_2_type: active0
	358	\|---trip_point_3_temp: 60000
	359	\|---trip_point_3_type: active1
	360	\|---cdev0: --->/sys/class/thermal/cooling_device0
	361	\|---cdev0_trip_point: 1 /* cdev0 can be used for passive */
db916513	362	\|---cdev0_weight: 1024
38bb0849 FP	363	\|---cdev1: --->/sys/class/thermal/cooling_device3
38bb0849 FP	364	\|---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/
db916513	365	\|---cdev1_weight: 1024
203d3d4a ZR	366
203d3d4a ZR	367	\|cooling_device0:
38bb0849 FP	368	\|---type: Processor
	369	\|---max_state: 8
	370	\|---cur_state: 0
203d3d4a ZR	371
203d3d4a ZR	372	\|cooling_device3:
38bb0849 FP	373	\|---type: Fan
	374	\|---max_state: 2
	375	\|---cur_state: 0
e9ae7107 ZR	376
	377	/sys/class/hwmon:
	378
	379	\|hwmon0:
38bb0849 FP	380	\|---name: acpitz
	381	\|---temp1_input: 37000
	382	\|---temp1_crit: 100000
4cb18728 D	383
	384	4. Event Notification
	385
	386	The framework includes a simple notification mechanism, in the form of a
	387	netlink event. Netlink socket initialization is done during the _init_
	388	of the framework. Drivers which intend to use the notification mechanism
2d58d7ea	389	just need to call thermal_generate_netlink_event() with two arguments viz
8ab3e6a0 EV	390	(originator, event). The originator is a pointer to struct thermal_zone_device
	391	from where the event has been originated. An integer which represents the
	392	thermal zone device will be used in the message to identify the zone. The
4cb18728 D	393	event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL,
	394	THERMAL_DEV_FAULT}. Notification can be sent when the current temperature
	395	crosses any of the configured thresholds.
6ea083b1 D	396
	397	5. Export Symbol APIs:
	398
	399	5.1: get_tz_trend:
	400	This function returns the trend of a thermal zone, i.e the rate of change
	401	of temperature of the thermal zone. Ideally, the thermal sensor drivers
	402	are supposed to implement the callback. If they don't, the thermal
	403	framework calculated the trend by comparing the previous and the current
	404	temperature values.
	405
	406	5.2:get_thermal_instance:
	407	This function returns the thermal_instance corresponding to a given
	408	{thermal_zone, cooling_device, trip_point} combination. Returns NULL
	409	if such an instance does not exist.
	410
7b73c993	411	5.3:thermal_notify_framework:
6ea083b1 D	412	This function handles the trip events from sensor drivers. It starts
	413	throttling the cooling devices according to the policy configured.
	414	For CRITICAL and HOT trip points, this notifies the respective drivers,
	415	and does actual throttling for other trip points i.e ACTIVE and PASSIVE.
	416	The throttling policy is based on the configured platform data; if no
	417	platform data is provided, this uses the step_wise throttling policy.
	418
	419	5.4:thermal_cdev_update:
	420	This function serves as an arbitrator to set the state of a cooling
	421	device. It sets the cooling device to the deepest cooling state if
	422	possible.