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@xxxxxxxxx> > Cc: Zhang Rui <rui.zhang@xxxxxxxxx> > Cc: Sujith Thomas <sujith.thomas@xxxxxxxxx> 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@xxxxxxxxx>, Zhang Rui <rui.zhang@xxxxxxxxx> > + > +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@xxxxxxxxx>, Zhang Rui <rui.zhang@xxxxxxxxx> > - > -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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
