diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/thermal/sysfs-api.txt | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt new file mode 100644 index 00000000000..5776e090359 --- /dev/null +++ b/Documentation/thermal/sysfs-api.txt @@ -0,0 +1,246 @@ +Generic Thermal Sysfs driver How To +========================= + +Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> + +Updated: 2 January 2008 + +Copyright (c) 2008 Intel Corporation + + +0. Introduction + +The generic thermal sysfs provides a set of interfaces for thermal zone devices (sensors) +and thermal cooling devices (fan, processor...) to register with the thermal management +solution and to be a part of it. + +This how-to focusses 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 callbacks. + .bind: bind the thermal zone device with a thermal cooling device. + .unbind: unbing 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 callbacks. + .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 + +All thermal sysfs attributes will be represented under /sys/class/thermal +/sys/class/thermal/ + +Thermal zone device sys I/F, created once it's registered: +|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: +|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 + + +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 exection. + +|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 + + +*************************** +* Thermal zone attributes * +*************************** + +type Strings which represent the thermal zone type. + This is given by thermal zone driver as part of registration. + Eg: "ACPI thermal zone" indicates it's a ACPI thermal device + RO + Optional + +temp Current temperature as reported by thermal zone (sensor) + Unit: degree celsius + RO + Required + +mode One of the predifned 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: degree celsius + RO + Optional + +trip_point_[0-*]_type Strings which indicate the type of the trip point + Eg. 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 assocated 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 + Optional + +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 thermale_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: ACPI thermal zone + |-----temp: 37 + |-----mode: kernel + |-----trip_point_0_temp: 100 + |-----trip_point_0_type: critical + |-----trip_point_1_temp: 80 + |-----trip_point_1_type: passive + |-----trip_point_2_temp: 70 + |-----trip_point_2_type: active[0] + |-----trip_point_3_temp: 60 + |-----trip_point_3_type: active[1] + |-----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 |