[v2,1/7] ABI: sysfs-class-thermal: create a file with thermal_zone ABI

Commit Message

Mauro Carvalho Chehab Sept. 30, 2021, 9:44 a.m. UTC

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.

Signed-off-by: Mauro Carvalho Chehab <[e-mail]>
---

See [PATCH v2 0/7] at: https://lore.kernel.org/all/[e-mail]/

 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

Comments

Rafael J. Wysocki Oct. 1, 2021, 4:57 p.m. UTC | #1

On Thu, Sep 30, 2021 at 11:45 AM Mauro Carvalho Chehab
<[e-mail]> 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.

So the subject of the patch should be something like

thermal: Move ABI documentation do Documentation/ABI

Also please mention the MAINTAINERS update in the changelog.

> Signed-off-by: Mauro Carvalho Chehab <[e-mail]>
> ---
>
> See [PATCH v2 0/7] at: https://lore.kernel.org/all/[e-mail]/
>
>  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 9b765cbc90d1..179eadaebe76 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -18653,7 +18653,9 @@ L:      [e-mail]
>  S:     Supported
>  Q:     https://patchwork.kernel.org/project/linux-pm/list/
>  T:     git git://git.kernel.org/pub/scm/linux/kernel/git/thermal/linux.git
> +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
>

Patch

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 9b765cbc90d1..179eadaebe76 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -18653,7 +18653,9 @@  L:	[e-mail]
 S:	Supported
 Q:	https://patchwork.kernel.org/project/linux-pm/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/thermal/linux.git
+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