thermal: sysfs-api.txt - reformat for improved readability
authorFrans Pop <elendil@planet.nl>
Mon, 26 Oct 2009 07:38:59 +0000 (08:38 +0100)
committerLen Brown <len.brown@intel.com>
Thu, 5 Nov 2009 23:06:05 +0000 (18:06 -0500)
The document currently uses large indentations which make the text
too wide for easy readability. Also improve general consistency.

Signed-off-by: Frans Pop <elendil@planet.nl>
Acked-by: Zhang Rui <rui.zhang@intel.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Len Brown <len.brown@intel.com>
Documentation/thermal/sysfs-api.txt

index 70d68ce8640a0f1490f3e126f6526ab58a62a581..895337f8c6ba9fc1d4cf28b22e95107b9cb32ddc 100644 (file)
@@ -1,5 +1,5 @@
 Generic Thermal Sysfs driver How To
-=========================
+===================================
 
 Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>
 
@@ -10,20 +10,20 @@ 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.
+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.
+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.
+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
@@ -31,77 +31,77 @@ and throttle appropriate devices.
 1. thermal sysfs driver interface functions
 
 1.1 thermal zone device interface
-1.1.1 struct thermal_zone_device *thermal_zone_device_register(char *name, int trips,
-                               void *devdata, struct thermal_zone_device_ops *ops)
-
-       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.
-
-       name: the thermal zone name.
-       trips: the total number of trip points this thermal zone supports.
-       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 (user/kernel) of the thermal zone.
-                          "kernel" means thermal management is done in kernel.
-                          "user" will prevent kernel thermal driver actions upon trip points
-                          so that user applications can take charge of thermal management.
-               .set_mode: set the mode (user/kernel) 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.
+1.1.1 struct thermal_zone_device *thermal_zone_device_register(char *name,
+               int trips, void *devdata, struct thermal_zone_device_ops *ops)
+
+    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.
+
+    name: the thermal zone name.
+    trips: the total number of trip points this thermal zone supports.
+    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 (user/kernel) of the thermal zone.
+           - "kernel" means thermal management is done in kernel.
+           - "user" will prevent kernel thermal driver actions upon trip points
+             so that user applications can take charge of thermal management.
+       .set_mode: set the mode (user/kernel) 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.
 
 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.
+    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.
+               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.
+    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);
+               int trip, struct thermal_cooling_device *cdev);
 
-       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.
+    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.
 
 1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
-                               int trip, struct thermal_cooling_device *cdev);
+               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.
+    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.
 
 2. sysfs attributes structure
 
@@ -114,153 +114,157 @@ 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
-       |-----trip_point_[0-*]_temp:    Trip point temperature
-       |-----trip_point_[0-*]_type:    Trip point type
+    |---type:                  Type of the thermal zone
+    |---temp:                  Current temperature
+    |---mode:                  Working mode of the thermal zone
+    |---trip_point_[0-*]_temp: Trip point temperature
+    |---trip_point_[0-*]_type: Trip point type
 
 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
+    |---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
 
 
-These 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
-thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device successful execution.
+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-*]:                The [0-*]th cooling device in the current thermal zone
-       |-----cdev[0-*]_trip_point:     Trip point that cdev[0-*] is associated with
+/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
 
 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.
+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-*].
+    |---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.
-                               Eg: "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 [kernel, user]
-                               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.
-                               RW
-                               Optional
-                               kernel  = Thermal management in kernel thermal zone driver.
-                               user    = Preventing kernel thermal zone driver actions upon
-                                         trip points so that user application can take full
-                                         charge of the thermal management.
-
-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
-
-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
-
-******************************
-* Cooling device  attributes *
-******************************
-
-type                           String which represents the type of device
-                               eg: For generic ACPI: this should be "Fan",
-                               "Processor" or "LCD"
-                               eg. For memory controller device on intel_menlow platform:
-                               this 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
+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 [kernel, user].
+       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.
+       kernel  = Thermal management in kernel thermal zone driver.
+       user    = Preventing kernel thermal zone driver actions upon
+                 trip points so that user application can take full
+                 charge of the thermal management.
+       RW, Optional
+
+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
+
+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
+
+*****************************
+* 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.
-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:
+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.
+
+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:                     kernel
-       |-----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 */
-       |-----cdev1:                    --->/sys/class/thermal/cooling_device3
-       |-----cdev1_trip_point:         2       /* cdev1 can be used for active[0]*/
+    |---type:                  acpitz
+    |---temp:                  37000
+    |---mode:                  kernel
+    |---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 */
+    |---cdev1:                 --->/sys/class/thermal/cooling_device3
+    |---cdev1_trip_point:      2       /* cdev1 can be used for active[0]*/
 
 |cooling_device0:
-       |-----type:                     Processor
-       |-----max_state:                8
-       |-----cur_state:                0
+    |---type:                  Processor
+    |---max_state:             8
+    |---cur_state:             0
 
 |cooling_device3:
-       |-----type:                     Fan
-       |-----max_state:                2
-       |-----cur_state:                0
+    |---type:                  Fan
+    |---max_state:             2
+    |---cur_state:             0
 
 /sys/class/hwmon:
 
 |hwmon0:
-       |-----name:                     acpitz
-       |-----temp1_input:              37000
-       |-----temp1_crit:               100000
+    |---name:                  acpitz
+    |---temp1_input:           37000
+    |---temp1_crit:            100000