| Message ID | 864dd17a1bff58770b1c1dc0b430bd26b6d7fa01.1633595141.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| State | Mainlined, archived |
| Headers | show |
| Series | [v2] thermal: Move ABI documentation do Documentation/ABI | expand |
On Thu, Oct 7, 2021 at 10:25 AM Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > > The thermal ABI is described, together with the internal > development details at: > > Documentation/driver-api/thermal/sysfs-api.rst > > Move the sysfs API description to Documentation/ABI, > ensuring that scripts/get_abi.pl will properly parse it. > > While here, also update MAINTAINERS for it to point to > the documentation. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> There is a typo in the subject, but I can fix it up. Daniel, would you mind if I applied this? > --- > Documentation/ABI/testing/sysfs-class-thermal | 259 ++++++++++++++++++ > .../driver-api/thermal/sysfs-api.rst | 225 +-------------- > MAINTAINERS | 2 + > 3 files changed, 264 insertions(+), 222 deletions(-) > create mode 100644 Documentation/ABI/testing/sysfs-class-thermal > > diff --git a/Documentation/ABI/testing/sysfs-class-thermal b/Documentation/ABI/testing/sysfs-class-thermal > new file mode 100644 > index 000000000000..2c52bb1f864c > --- /dev/null > +++ b/Documentation/ABI/testing/sysfs-class-thermal > @@ -0,0 +1,259 @@ > +What: /sys/class/thermal/thermal_zoneX/type > +Description: > + 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 > + shouldbe a short, lowercase string, not containing spaces nor > + dashes. > + > + RO, Required > + > +What: /sys/class/thermal/thermal_zoneX/temp > +Description: > + Current temperature as reported by thermal zone (sensor). > + > + Unit: millidegree Celsius > + > + RO, Required > + > +What: /sys/class/thermal/thermal_zoneX/mode > +Description: > + One of the predefined values in [enabled, disabled]. > + This file gives information about the algorithm that is > + currently managing the thermal zone. It can be either default > + kernel based algorithm or user space application. > + > + enabled > + enable Kernel Thermal management. > + disabled > + Preventing kernel thermal zone driver actions upon > + trip points so that user application can take full > + charge of the thermal management. > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/policy > +Description: > + One of the various thermal governors used for a particular zone. > + > + RW, Required > + > +What: /sys/class/thermal/thermal_zoneX/available_policies > +Description: > + Available thermal governors which can be used for a > + particular zone. > + > + RO, Required > + > +What: /sys/class/thermal/thermal_zoneX/trip_point_Y_temp > +Description: > + The temperature above which trip point will be fired. > + > + Unit: millidegree Celsius > + > + RO, Optional > + > +What: /sys/class/thermal/thermal_zoneX/trip_point_Y_type > +Description: > + 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 > + > +What: /sys/class/thermal/thermal_zoneX/trip_point_Y_hyst > +Description: > + The hysteresis value for a trip point, represented as an > + integer. > + > + Unit: Celsius > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/cdevY > +Description: > + Sysfs link to the thermal cooling device node where the sys I/F > + for cooling device throttling control represents. > + > + RO, Optional > + > +What: /sys/class/thermal/thermal_zoneX/cdevY_trip_point > +Description: > + The trip point in this thermal zone which `cdev[0-*]` is > + associated with; -1 means the cooling device is not > + associated with any trip point. > + > + RO, Optional > + > +What: /sys/class/thermal/thermal_zoneX/cdevY_weight > +Description: > + The influence of `cdev[0-*]` in this thermal zone. This value > + is relative to the rest of cooling devices in the thermal > + zone. For example, if a cooling device has a weight double > + than that of other, it's twice as effective in cooling the > + thermal zone. > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/emul_temp > +Description: > + Interface to set the emulated temperature method in thermal zone > + (sensor). After setting this temperature, the thermal zone may > + pass this temperature to platform emulation function if > + registered or cache it locally. This is useful in debugging > + different temperature threshold and its associated cooling > + action. This is write only node and writing 0 on this node > + should disable emulation. > + > + Unit: millidegree Celsius > + > + WO, Optional > + > + WARNING: > + Be careful while enabling this option on production systems, > + because userland can easily disable the thermal policy by simply > + flooding this sysfs node with low temperature values. > + > + > +What: /sys/class/thermal/thermal_zoneX/k_d > +Description: > + The derivative term of the power allocator governor's PID > + controller. For more information see > + Documentation/driver-api/thermal/power_allocator.rst > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/k_i > +Description: > + The integral term of the power allocator governor's PID > + controller. This term allows the PID controller to compensate > + for long term drift. For more information see > + Documentation/driver-api/thermal/power_allocator.rst > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/k_po > +Description: > + The proportional term of the power allocator governor's PID > + controller during temperature overshoot. Temperature overshoot > + is when the current temperature is above the "desired > + temperature" trip point. For more information see > + Documentation/driver-api/thermal/power_allocator.rst > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/k_pu > +Description: > + The proportional term of the power allocator governor's PID > + controller during temperature undershoot. Temperature undershoot > + is when the current temperature is below the "desired > + temperature" trip point. For more information see > + Documentation/driver-api/thermal/power_allocator.rst > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/integral_cutoff > +Description: > + Temperature offset from the desired temperature trip point > + above which the integral term of the power allocator > + governor's PID controller starts accumulating errors. For > + example, if integral_cutoff is 0, then the integral term only > + accumulates error when temperature is above the desired > + temperature trip point. For more information see > + Documentation/driver-api/thermal/power_allocator.rst > + > + Unit: millidegree Celsius > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/slope > +Description: > + The slope constant used in a linear extrapolation model > + to determine a hotspot temperature based off the sensor's > + raw readings. It is up to the device driver to determine > + the usage of these values. > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/offset > +Description: > + The offset constant used in a linear extrapolation model > + to determine a hotspot temperature based off the sensor's > + raw readings. It is up to the device driver to determine > + the usage of these values. > + > + RW, Optional > + > +What: /sys/class/thermal/thermal_zoneX/sustainable_power > +Description: > + An estimate of the sustained power that can be dissipated by > + the thermal zone. Used by the power allocator governor. For > + more information see > + Documentation/driver-api/thermal/power_allocator.rst > + > + Unit: milliwatts > + > + RW, Optional > + > +What: /sys/class/thermal/cooling_deviceX/type > +Description: > + 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 > + > +What: /sys/class/thermal/cooling_deviceX/max_state > +Description: > + The maximum permissible cooling state of this cooling device. > + > + RO, Required > + > +What: /sys/class/thermal/cooling_deviceX/cur_state > +Description: > + 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 > + > +What: /sys/class/thermal/cooling_deviceX/stats/reset > +Description: > + Writing any value resets the cooling device's statistics. > + > + WO, Required > + > +What: /sys/class/thermal/cooling_deviceX/stats/time_in_state_ms: > +Description: > + The amount of time spent by the cooling device in various > + cooling states. The output will have "<state> <time>" pair > + in each line, which will mean this cooling device spent <time> > + msec of time at <state>. > + > + Output will have one line for each of the supported states. > + > + RO, Required > + > +What: /sys/class/thermal/cooling_deviceX/stats/total_trans > +Description: > + A single positive value showing the total number of times > + the state of a cooling device is changed. > + > + RO, Required > + > +What: /sys/class/thermal/cooling_deviceX/stats/trans_table > +Description: > + This gives fine grained information about all the cooling state > + transitions. The cat output here is a two dimensional matrix, > + where an entry <i,j> (row i, column j) represents the number > + of transitions from State_i to State_j. If the transition > + table is bigger than PAGE_SIZE, reading this will return > + an -EFBIG error. > + > + RO, Required > diff --git a/Documentation/driver-api/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst > index c93fa5e961a0..2e0f79a9e2ee 100644 > --- a/Documentation/driver-api/thermal/sysfs-api.rst > +++ b/Documentation/driver-api/thermal/sysfs-api.rst > @@ -428,6 +428,9 @@ 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. > > +Please read Documentation/ABI/testing/sysfs-class-thermal for thermal > +zone and cooling device attribute details. > + > :: > > /sys/class/hwmon/hwmon[0-*]: > @@ -437,228 +440,6 @@ ACPI thermal zones. > > Please read Documentation/hwmon/sysfs-interface.rst for additional information. > > -Thermal zone attributes > ------------------------ > - > -type > - Strings which represent the thermal zone type. > - This is given by thermal zone driver as part of registration. > - E.g: "acpitz" indicates it's an ACPI thermal device. > - In order to keep it consistent with hwmon sys attribute; this should > - be a short, lowercase string, not containing spaces nor dashes. > - RO, Required > - > -temp > - Current temperature as reported by thermal zone (sensor). > - Unit: millidegree Celsius > - RO, Required > - > -mode > - One of the predefined values in [enabled, disabled]. > - This file gives information about the algorithm that is currently > - managing the thermal zone. It can be either default kernel based > - algorithm or user space application. > - > - enabled > - enable Kernel Thermal management. > - disabled > - Preventing kernel thermal zone driver actions upon > - trip points so that user application can take full > - charge of the thermal management. > - > - RW, Optional > - > -policy > - One of the various thermal governors used for a particular zone. > - > - RW, Required > - > -available_policies > - Available thermal governors which can be used for a particular zone. > - > - RO, Required > - > -`trip_point_[0-*]_temp` > - The temperature above which trip point will be fired. > - > - Unit: millidegree Celsius > - > - RO, Optional > - > -`trip_point_[0-*]_type` > - Strings which indicate the type of the trip point. > - > - E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI > - thermal zone. > - > - RO, Optional > - > -`trip_point_[0-*]_hyst` > - The hysteresis value for a trip point, represented as an integer > - Unit: Celsius > - RW, Optional > - > -`cdev[0-*]` > - Sysfs link to the thermal cooling device node where the sys I/F > - for cooling device throttling control represents. > - > - RO, Optional > - > -`cdev[0-*]_trip_point` > - The trip point in this thermal zone which `cdev[0-*]` is associated > - with; -1 means the cooling device is not associated with any trip > - point. > - > - RO, Optional > - > -`cdev[0-*]_weight` > - The influence of `cdev[0-*]` in this thermal zone. This value > - is relative to the rest of cooling devices in the thermal > - zone. For example, if a cooling device has a weight double > - than that of other, it's twice as effective in cooling the > - thermal zone. > - > - RW, Optional > - > -emul_temp > - Interface to set the emulated temperature method in thermal zone > - (sensor). After setting this temperature, the thermal zone may pass > - this temperature to platform emulation function if registered or > - cache it locally. This is useful in debugging different temperature > - threshold and its associated cooling action. This is write only node > - and writing 0 on this node should disable emulation. > - Unit: millidegree Celsius > - > - WO, Optional > - > - WARNING: > - Be careful while enabling this option on production systems, > - because userland can easily disable the thermal policy by simply > - flooding this sysfs node with low temperature values. > - > -sustainable_power > - An estimate of the sustained power that can be dissipated by > - the thermal zone. Used by the power allocator governor. For > - more information see Documentation/driver-api/thermal/power_allocator.rst > - > - Unit: milliwatts > - > - RW, Optional > - > -k_po > - The proportional term of the power allocator governor's PID > - controller during temperature overshoot. Temperature overshoot > - is when the current temperature is above the "desired > - temperature" trip point. For more information see > - Documentation/driver-api/thermal/power_allocator.rst > - > - RW, Optional > - > -k_pu > - The proportional term of the power allocator governor's PID > - controller during temperature undershoot. Temperature undershoot > - is when the current temperature is below the "desired > - temperature" trip point. For more information see > - Documentation/driver-api/thermal/power_allocator.rst > - > - RW, Optional > - > -k_i > - The integral term of the power allocator governor's PID > - controller. This term allows the PID controller to compensate > - for long term drift. For more information see > - Documentation/driver-api/thermal/power_allocator.rst > - > - RW, Optional > - > -k_d > - The derivative term of the power allocator governor's PID > - controller. For more information see > - Documentation/driver-api/thermal/power_allocator.rst > - > - RW, Optional > - > -integral_cutoff > - Temperature offset from the desired temperature trip point > - above which the integral term of the power allocator > - governor's PID controller starts accumulating errors. For > - example, if integral_cutoff is 0, then the integral term only > - accumulates error when temperature is above the desired > - temperature trip point. For more information see > - Documentation/driver-api/thermal/power_allocator.rst > - > - Unit: millidegree Celsius > - > - RW, Optional > - > -slope > - The slope constant used in a linear extrapolation model > - to determine a hotspot temperature based off the sensor's > - raw readings. It is up to the device driver to determine > - the usage of these values. > - > - RW, Optional > - > -offset > - The offset constant used in a linear extrapolation model > - to determine a hotspot temperature based off the sensor's > - raw readings. It is up to the device driver to determine > - the usage of these values. > - > - 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 > - > -stats/reset > - Writing any value resets the cooling device's statistics. > - WO, Required > - > -stats/time_in_state_ms: > - The amount of time spent by the cooling device in various cooling > - states. The output will have "<state> <time>" pair in each line, which > - will mean this cooling device spent <time> msec of time at <state>. > - Output will have one line for each of the supported states. > - RO, Required > - > - > -stats/total_trans: > - A single positive value showing the total number of times the state of a > - cooling device is changed. > - > - RO, Required > - > -stats/trans_table: > - This gives fine grained information about all the cooling state > - transitions. The cat output here is a two dimensional matrix, where an > - entry <i,j> (row i, column j) represents the number of transitions from > - State_i to State_j. If the transition table is bigger than PAGE_SIZE, > - reading this will return an -EFBIG error. > - RO, Required > - > 3. A simple implementation > ========================== > > diff --git a/MAINTAINERS b/MAINTAINERS > index 7cfd63ce7122..a8fa66402b05 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -18697,7 +18697,9 @@ L: linux-pm@vger.kernel.org > S: Supported > Q: https://patchwork.kernel.org/project/linux-pm/list/ > T: git git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git thermal > +F: Documentation/ABI/testing/sysfs-class-thermal > F: Documentation/devicetree/bindings/thermal/ > +F: Documentation/driver-api/thermal/ > F: drivers/thermal/ > F: include/linux/cpu_cooling.h > F: include/linux/thermal.h > -- > 2.31.1 >
On 07/10/2021 18:39, Rafael J. Wysocki wrote: > On Thu, Oct 7, 2021 at 10:25 AM Mauro Carvalho Chehab > <mchehab+huawei@kernel.org> wrote: >> >> The thermal ABI is described, together with the internal >> development details at: >> >> Documentation/driver-api/thermal/sysfs-api.rst >> >> Move the sysfs API description to Documentation/ABI, >> ensuring that scripts/get_abi.pl will properly parse it. >> >> While here, also update MAINTAINERS for it to point to >> the documentation. >> >> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > There is a typo in the subject, but I can fix it up. > > Daniel, would you mind if I applied this? Acked-by: Daniel Lezcano <daniel.lezcano@linaro.org>
On Thu, Oct 7, 2021 at 6:42 PM Daniel Lezcano <daniel.lezcano@linaro.org> wrote: > > On 07/10/2021 18:39, Rafael J. Wysocki wrote: > > On Thu, Oct 7, 2021 at 10:25 AM Mauro Carvalho Chehab > > <mchehab+huawei@kernel.org> wrote: > >> > >> The thermal ABI is described, together with the internal > >> development details at: > >> > >> Documentation/driver-api/thermal/sysfs-api.rst > >> > >> Move the sysfs API description to Documentation/ABI, > >> ensuring that scripts/get_abi.pl will properly parse it. > >> > >> While here, also update MAINTAINERS for it to point to > >> the documentation. > >> > >> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > > > There is a typo in the subject, but I can fix it up. > > > > Daniel, would you mind if I applied this? > > Acked-by: Daniel Lezcano <daniel.lezcano@linaro.org> Applied as 5.16 material, thanks!
diff --git a/Documentation/ABI/testing/sysfs-class-thermal b/Documentation/ABI/testing/sysfs-class-thermal new file mode 100644 index 000000000000..2c52bb1f864c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-thermal @@ -0,0 +1,259 @@ +What: /sys/class/thermal/thermal_zoneX/type +Description: + 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 + shouldbe a short, lowercase string, not containing spaces nor + dashes. + + RO, Required + +What: /sys/class/thermal/thermal_zoneX/temp +Description: + Current temperature as reported by thermal zone (sensor). + + Unit: millidegree Celsius + + RO, Required + +What: /sys/class/thermal/thermal_zoneX/mode +Description: + One of the predefined values in [enabled, disabled]. + This file gives information about the algorithm that is + currently managing the thermal zone. It can be either default + kernel based algorithm or user space application. + + enabled + enable Kernel Thermal management. + disabled + Preventing kernel thermal zone driver actions upon + trip points so that user application can take full + charge of the thermal management. + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/policy +Description: + One of the various thermal governors used for a particular zone. + + RW, Required + +What: /sys/class/thermal/thermal_zoneX/available_policies +Description: + Available thermal governors which can be used for a + particular zone. + + RO, Required + +What: /sys/class/thermal/thermal_zoneX/trip_point_Y_temp +Description: + The temperature above which trip point will be fired. + + Unit: millidegree Celsius + + RO, Optional + +What: /sys/class/thermal/thermal_zoneX/trip_point_Y_type +Description: + 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 + +What: /sys/class/thermal/thermal_zoneX/trip_point_Y_hyst +Description: + The hysteresis value for a trip point, represented as an + integer. + + Unit: Celsius + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/cdevY +Description: + Sysfs link to the thermal cooling device node where the sys I/F + for cooling device throttling control represents. + + RO, Optional + +What: /sys/class/thermal/thermal_zoneX/cdevY_trip_point +Description: + The trip point in this thermal zone which `cdev[0-*]` is + associated with; -1 means the cooling device is not + associated with any trip point. + + RO, Optional + +What: /sys/class/thermal/thermal_zoneX/cdevY_weight +Description: + The influence of `cdev[0-*]` in this thermal zone. This value + is relative to the rest of cooling devices in the thermal + zone. For example, if a cooling device has a weight double + than that of other, it's twice as effective in cooling the + thermal zone. + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/emul_temp +Description: + Interface to set the emulated temperature method in thermal zone + (sensor). After setting this temperature, the thermal zone may + pass this temperature to platform emulation function if + registered or cache it locally. This is useful in debugging + different temperature threshold and its associated cooling + action. This is write only node and writing 0 on this node + should disable emulation. + + Unit: millidegree Celsius + + WO, Optional + + WARNING: + Be careful while enabling this option on production systems, + because userland can easily disable the thermal policy by simply + flooding this sysfs node with low temperature values. + + +What: /sys/class/thermal/thermal_zoneX/k_d +Description: + The derivative term of the power allocator governor's PID + controller. For more information see + Documentation/driver-api/thermal/power_allocator.rst + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/k_i +Description: + The integral term of the power allocator governor's PID + controller. This term allows the PID controller to compensate + for long term drift. For more information see + Documentation/driver-api/thermal/power_allocator.rst + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/k_po +Description: + The proportional term of the power allocator governor's PID + controller during temperature overshoot. Temperature overshoot + is when the current temperature is above the "desired + temperature" trip point. For more information see + Documentation/driver-api/thermal/power_allocator.rst + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/k_pu +Description: + The proportional term of the power allocator governor's PID + controller during temperature undershoot. Temperature undershoot + is when the current temperature is below the "desired + temperature" trip point. For more information see + Documentation/driver-api/thermal/power_allocator.rst + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/integral_cutoff +Description: + Temperature offset from the desired temperature trip point + above which the integral term of the power allocator + governor's PID controller starts accumulating errors. For + example, if integral_cutoff is 0, then the integral term only + accumulates error when temperature is above the desired + temperature trip point. For more information see + Documentation/driver-api/thermal/power_allocator.rst + + Unit: millidegree Celsius + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/slope +Description: + The slope constant used in a linear extrapolation model + to determine a hotspot temperature based off the sensor's + raw readings. It is up to the device driver to determine + the usage of these values. + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/offset +Description: + The offset constant used in a linear extrapolation model + to determine a hotspot temperature based off the sensor's + raw readings. It is up to the device driver to determine + the usage of these values. + + RW, Optional + +What: /sys/class/thermal/thermal_zoneX/sustainable_power +Description: + An estimate of the sustained power that can be dissipated by + the thermal zone. Used by the power allocator governor. For + more information see + Documentation/driver-api/thermal/power_allocator.rst + + Unit: milliwatts + + RW, Optional + +What: /sys/class/thermal/cooling_deviceX/type +Description: + 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 + +What: /sys/class/thermal/cooling_deviceX/max_state +Description: + The maximum permissible cooling state of this cooling device. + + RO, Required + +What: /sys/class/thermal/cooling_deviceX/cur_state +Description: + 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 + +What: /sys/class/thermal/cooling_deviceX/stats/reset +Description: + Writing any value resets the cooling device's statistics. + + WO, Required + +What: /sys/class/thermal/cooling_deviceX/stats/time_in_state_ms: +Description: + The amount of time spent by the cooling device in various + cooling states. The output will have "<state> <time>" pair + in each line, which will mean this cooling device spent <time> + msec of time at <state>. + + Output will have one line for each of the supported states. + + RO, Required + +What: /sys/class/thermal/cooling_deviceX/stats/total_trans +Description: + A single positive value showing the total number of times + the state of a cooling device is changed. + + RO, Required + +What: /sys/class/thermal/cooling_deviceX/stats/trans_table +Description: + This gives fine grained information about all the cooling state + transitions. The cat output here is a two dimensional matrix, + where an entry <i,j> (row i, column j) represents the number + of transitions from State_i to State_j. If the transition + table is bigger than PAGE_SIZE, reading this will return + an -EFBIG error. + + RO, Required diff --git a/Documentation/driver-api/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst index c93fa5e961a0..2e0f79a9e2ee 100644 --- a/Documentation/driver-api/thermal/sysfs-api.rst +++ b/Documentation/driver-api/thermal/sysfs-api.rst @@ -428,6 +428,9 @@ 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. +Please read Documentation/ABI/testing/sysfs-class-thermal for thermal +zone and cooling device attribute details. + :: /sys/class/hwmon/hwmon[0-*]: @@ -437,228 +440,6 @@ ACPI thermal zones. Please read Documentation/hwmon/sysfs-interface.rst for additional information. -Thermal zone attributes ------------------------ - -type - Strings which represent the thermal zone type. - This is given by thermal zone driver as part of registration. - E.g: "acpitz" indicates it's an ACPI thermal device. - In order to keep it consistent with hwmon sys attribute; this should - be a short, lowercase string, not containing spaces nor dashes. - RO, Required - -temp - Current temperature as reported by thermal zone (sensor). - Unit: millidegree Celsius - RO, Required - -mode - One of the predefined values in [enabled, disabled]. - This file gives information about the algorithm that is currently - managing the thermal zone. It can be either default kernel based - algorithm or user space application. - - enabled - enable Kernel Thermal management. - disabled - Preventing kernel thermal zone driver actions upon - trip points so that user application can take full - charge of the thermal management. - - RW, Optional - -policy - One of the various thermal governors used for a particular zone. - - RW, Required - -available_policies - Available thermal governors which can be used for a particular zone. - - RO, Required - -`trip_point_[0-*]_temp` - The temperature above which trip point will be fired. - - Unit: millidegree Celsius - - RO, Optional - -`trip_point_[0-*]_type` - Strings which indicate the type of the trip point. - - E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI - thermal zone. - - RO, Optional - -`trip_point_[0-*]_hyst` - The hysteresis value for a trip point, represented as an integer - Unit: Celsius - RW, Optional - -`cdev[0-*]` - Sysfs link to the thermal cooling device node where the sys I/F - for cooling device throttling control represents. - - RO, Optional - -`cdev[0-*]_trip_point` - The trip point in this thermal zone which `cdev[0-*]` is associated - with; -1 means the cooling device is not associated with any trip - point. - - RO, Optional - -`cdev[0-*]_weight` - The influence of `cdev[0-*]` in this thermal zone. This value - is relative to the rest of cooling devices in the thermal - zone. For example, if a cooling device has a weight double - than that of other, it's twice as effective in cooling the - thermal zone. - - RW, Optional - -emul_temp - Interface to set the emulated temperature method in thermal zone - (sensor). After setting this temperature, the thermal zone may pass - this temperature to platform emulation function if registered or - cache it locally. This is useful in debugging different temperature - threshold and its associated cooling action. This is write only node - and writing 0 on this node should disable emulation. - Unit: millidegree Celsius - - WO, Optional - - WARNING: - Be careful while enabling this option on production systems, - because userland can easily disable the thermal policy by simply - flooding this sysfs node with low temperature values. - -sustainable_power - An estimate of the sustained power that can be dissipated by - the thermal zone. Used by the power allocator governor. For - more information see Documentation/driver-api/thermal/power_allocator.rst - - Unit: milliwatts - - RW, Optional - -k_po - The proportional term of the power allocator governor's PID - controller during temperature overshoot. Temperature overshoot - is when the current temperature is above the "desired - temperature" trip point. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -k_pu - The proportional term of the power allocator governor's PID - controller during temperature undershoot. Temperature undershoot - is when the current temperature is below the "desired - temperature" trip point. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -k_i - The integral term of the power allocator governor's PID - controller. This term allows the PID controller to compensate - for long term drift. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -k_d - The derivative term of the power allocator governor's PID - controller. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -integral_cutoff - Temperature offset from the desired temperature trip point - above which the integral term of the power allocator - governor's PID controller starts accumulating errors. For - example, if integral_cutoff is 0, then the integral term only - accumulates error when temperature is above the desired - temperature trip point. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - Unit: millidegree Celsius - - RW, Optional - -slope - The slope constant used in a linear extrapolation model - to determine a hotspot temperature based off the sensor's - raw readings. It is up to the device driver to determine - the usage of these values. - - RW, Optional - -offset - The offset constant used in a linear extrapolation model - to determine a hotspot temperature based off the sensor's - raw readings. It is up to the device driver to determine - the usage of these values. - - 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 - -stats/reset - Writing any value resets the cooling device's statistics. - WO, Required - -stats/time_in_state_ms: - The amount of time spent by the cooling device in various cooling - states. The output will have "<state> <time>" pair in each line, which - will mean this cooling device spent <time> msec of time at <state>. - Output will have one line for each of the supported states. - RO, Required - - -stats/total_trans: - A single positive value showing the total number of times the state of a - cooling device is changed. - - RO, Required - -stats/trans_table: - This gives fine grained information about all the cooling state - transitions. The cat output here is a two dimensional matrix, where an - entry <i,j> (row i, column j) represents the number of transitions from - State_i to State_j. If the transition table is bigger than PAGE_SIZE, - reading this will return an -EFBIG error. - RO, Required - 3. A simple implementation ========================== diff --git a/MAINTAINERS b/MAINTAINERS index 7cfd63ce7122..a8fa66402b05 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -18697,7 +18697,9 @@ L: linux-pm@vger.kernel.org S: Supported Q: https://patchwork.kernel.org/project/linux-pm/list/ T: git git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git thermal +F: Documentation/ABI/testing/sysfs-class-thermal F: Documentation/devicetree/bindings/thermal/ +F: Documentation/driver-api/thermal/ F: drivers/thermal/ F: include/linux/cpu_cooling.h F: include/linux/thermal.h
The thermal ABI is described, together with the internal development details at: Documentation/driver-api/thermal/sysfs-api.rst Move the sysfs API description to Documentation/ABI, ensuring that scripts/get_abi.pl will properly parse it. While here, also update MAINTAINERS for it to point to the documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/ABI/testing/sysfs-class-thermal | 259 ++++++++++++++++++ .../driver-api/thermal/sysfs-api.rst | 225 +-------------- MAINTAINERS | 2 + 3 files changed, 264 insertions(+), 222 deletions(-) create mode 100644 Documentation/ABI/testing/sysfs-class-thermal