| Message ID | 200908211102.33936.elendil@planet.nl (mailing list archive) |
|---|---|
| State | RFC, archived |
| Headers | show |
On Fri, 2009-08-21 at 17:02 +0800, Frans Pop wrote: > It is a more logical place to look and reduces the clutter in > the Documentation directory as the thermal directory is now empty > and can be removed. > > Signed-off-by: Frans Pop <elendil@planet.nl> > Cc: Zhang Rui <rui.zhang@intel.com> > Cc: Sujith Thomas <sujith.thomas@intel.com> NAK. this document describes the sysfs I/F of the GENERIC thermal driver. ACPI thermal driver is just the first user of this thermal sysfs driver. More drivers than ACPI will use this framework in the future. thanks, rui > > diff --git a/Documentation/acpi/thermal-sysfs-api.txt b/Documentation/acpi/thermal-sysfs-api.txt > new file mode 100644 > index 0000000..52b63c4 > --- /dev/null > +++ b/Documentation/acpi/thermal-sysfs-api.txt > @@ -0,0 +1,281 @@ > +Generic Thermal Sysfs driver How To > +=================================== > + > +Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> > + > +Updated: 21 August 2009 > + > +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 *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. > + > +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); > + > + 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); > + > + 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 > + > +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 > + |---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 > + > + > +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 > + > +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 [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 > + > +passive > + Attribute is only present for zones which do not have a passive > + cooling policy (_PSV) defined in ACPI. 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 (default interval: > + 10 seconds); the polling interval can be set in > + /proc/acpi/thermal/TZN/polling_frequency. > + Unit: millidegree Celsius > + RW, 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, the fan is listed in _AL0 > +method, and the zone hase a _PSV 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]*/ > + > +|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 > diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt > deleted file mode 100644 > index 52b63c4..0000000 > --- a/Documentation/thermal/sysfs-api.txt > +++ /dev/null > @@ -1,281 +0,0 @@ > -Generic Thermal Sysfs driver How To > -=================================== > - > -Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> > - > -Updated: 21 August 2009 > - > -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 *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. > - > -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); > - > - 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); > - > - 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 > - > -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 > - |---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 > - > - > -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 > - > -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 [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 > - > -passive > - Attribute is only present for zones which do not have a passive > - cooling policy (_PSV) defined in ACPI. 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 (default interval: > - 10 seconds); the polling interval can be set in > - /proc/acpi/thermal/TZN/polling_frequency. > - Unit: millidegree Celsius > - RW, 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, the fan is listed in _AL0 > -method, and the zone hase a _PSV 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]*/ > - > -|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 -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
diff --git a/Documentation/acpi/thermal-sysfs-api.txt b/Documentation/acpi/thermal-sysfs-api.txt new file mode 100644 index 0000000..52b63c4 --- /dev/null +++ b/Documentation/acpi/thermal-sysfs-api.txt @@ -0,0 +1,281 @@ +Generic Thermal Sysfs driver How To +=================================== + +Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> + +Updated: 21 August 2009 + +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 *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. + +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); + + 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); + + 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 + +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 + |---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 + + +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 + +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 [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 + +passive + Attribute is only present for zones which do not have a passive + cooling policy (_PSV) defined in ACPI. 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 (default interval: + 10 seconds); the polling interval can be set in + /proc/acpi/thermal/TZN/polling_frequency. + Unit: millidegree Celsius + RW, 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, the fan is listed in _AL0 +method, and the zone hase a _PSV 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]*/ + +|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 diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt deleted file mode 100644 index 52b63c4..0000000 --- a/Documentation/thermal/sysfs-api.txt +++ /dev/null @@ -1,281 +0,0 @@ -Generic Thermal Sysfs driver How To -=================================== - -Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> - -Updated: 21 August 2009 - -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 *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. - -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); - - 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); - - 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 - -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 - |---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 - - -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 - -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 [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 - -passive - Attribute is only present for zones which do not have a passive - cooling policy (_PSV) defined in ACPI. 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 (default interval: - 10 seconds); the polling interval can be set in - /proc/acpi/thermal/TZN/polling_frequency. - Unit: millidegree Celsius - RW, 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, the fan is listed in _AL0 -method, and the zone hase a _PSV 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]*/ - -|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
It is a more logical place to look and reduces the clutter in the Documentation directory as the thermal directory is now empty and can be removed. Signed-off-by: Frans Pop <elendil@planet.nl> Cc: Zhang Rui <rui.zhang@intel.com> Cc: Sujith Thomas <sujith.thomas@intel.com> -- To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html