Re: [PATCH v1 04/22] docs: thermal: convert to ReST

From: Zhang Rui
Date: Tue Jun 25 2019 - 09:40:27 EST

Next message: Thierry Reding: "Re: [PATCH V4 03/18] gpio: tegra: use resume_noirq for tegra gpio resume"
Previous message: Will Deacon: "Re: [PATCH v3 3/4] iommu/arm-smmu: Add support to handle Qcom's wait-for-safe logic"
Next in thread: Mauro Carvalho Chehab: "Re: [PATCH v1 04/22] docs: thermal: convert to ReST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

On ä, 2019-06-18 at 18:05 -0300, Mauro Carvalho Chehab wrote:
> Rename the thermal documentation files to ReST, add an
> index for them and adjust in order to produce a nice html
> output via the Sphinx build system.
>
> At its new index.rst, let's add a :orphan: while this is not linked
> to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>

Acked-by: Zhang Rui <rui.zhang@xxxxxxxxx>

should I apply this patch or you have a separate tree for all these
changes?

thanks,
rui
> ---
> Â...pu-cooling-api.txt => cpu-cooling-api.rst} |ÂÂ39 +-
> Â.../{exynos_thermal => exynos_thermal.rst}ÂÂÂÂ|ÂÂ47 +-
> Â...emulation => exynos_thermal_emulation.rst} |ÂÂ66 +--
> ÂDocumentation/thermal/index.rstÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂ18 +
> Â...el_powerclamp.txt => intel_powerclamp.rst} | 177 +++----
> Â.../{nouveau_thermal => nouveau_thermal.rst}ÂÂ|ÂÂ54 +-
> Â...ower_allocator.txt => power_allocator.rst} | 140 ++---
> Â.../thermal/{sysfs-api.txt => sysfs-api.rst}ÂÂ| 490 ++++++++++++--
> ----
> Â...hermal => x86_pkg_temperature_thermal.rst} |ÂÂ28 +-
> ÂMAINTAINERSÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂ2 +-
> Âinclude/linux/thermal.hÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂ4 +-
> Â11 files changed, 665 insertions(+), 400 deletions(-)
> Ârename Documentation/thermal/{cpu-cooling-api.txt => cpu-cooling-
> api.rst} (82%)
> Ârename Documentation/thermal/{exynos_thermal => exynos_thermal.rst}
> (67%)
> Ârename Documentation/thermal/{exynos_thermal_emulation =>
> exynos_thermal_emulation.rst} (36%)
> Âcreate mode 100644 Documentation/thermal/index.rst
> Ârename Documentation/thermal/{intel_powerclamp.txt =>
> intel_powerclamp.rst} (76%)
> Ârename Documentation/thermal/{nouveau_thermal =>
> nouveau_thermal.rst} (64%)
> Ârename Documentation/thermal/{power_allocator.txt =>
> power_allocator.rst} (74%)
> Ârename Documentation/thermal/{sysfs-api.txt => sysfs-api.rst} (66%)
> Ârename Documentation/thermal/{x86_pkg_temperature_thermal =>
> x86_pkg_temperature_thermal.rst} (80%)
>
> diff --git a/Documentation/thermal/cpu-cooling-api.txt
> b/Documentation/thermal/cpu-cooling-api.rst
> similarity index 82%
> rename from Documentation/thermal/cpu-cooling-api.txt
> rename to Documentation/thermal/cpu-cooling-api.rst
> index 7df567eaea1a..645d914c45a6 100644
> --- a/Documentation/thermal/cpu-cooling-api.txt
> +++ b/Documentation/thermal/cpu-cooling-api.rst
> @@ -1,5 +1,6 @@
> +=======================
> ÂCPU cooling APIs How To
> -===================================
> +=======================
> Â
> ÂWritten by Amit Daniel Kachhap <amit.kachhap@xxxxxxxxxx>
> Â
> @@ -8,40 +9,54 @@ Updated: 6 Jan 2015
> ÂCopyright (c)ÂÂ2012 Samsung Electronics Co., Ltd(http://www.samsung.
> com)
> Â
> Â0. Introduction
> +===============
> Â
> ÂThe generic cpu cooling(freq clipping) provides
> registration/unregistration APIs
> Âto the caller. The binding of the cooling devices to the trip point
> is left for
> Âthe user. The registration APIs returns the cooling device pointer.
> Â
> Â1. cpu cooling APIs
> +===================
> Â
> Â1.1 cpufreq registration/unregistration APIs
> -1.1.1 struct thermal_cooling_device *cpufreq_cooling_register(
> - struct cpumask *clip_cpus)
> +--------------------------------------------
> +
> +ÂÂÂÂ::
> +
> + struct thermal_cooling_device
> + *cpufreq_cooling_register(struct cpumask *clip_cpus)
> Â
> ÂÂÂÂÂThis interface function registers the cpufreq cooling device
> with the name
> ÂÂÂÂÂ"thermal-cpufreq-%x". This api can support multiple instances of
> cpufreq
> ÂÂÂÂÂcooling devices.
> Â
> -ÂÂÂclip_cpus: cpumask of cpus where the frequency constraints will
> happen.
> +ÂÂÂclip_cpus:
> + cpumask of cpus where the frequency constraints will happen.
> Â
> -1.1.2 struct thermal_cooling_device *of_cpufreq_cooling_register(
> - struct cpufreq_policy
> *policy)
> +ÂÂÂÂ::
> +
> + struct thermal_cooling_device
> + *of_cpufreq_cooling_register(struct cpufreq_policy *policy)
> Â
> ÂÂÂÂÂThis interface function registers the cpufreq cooling device
> with
> ÂÂÂÂÂthe name "thermal-cpufreq-%x" linking it with a device tree
> node, in
> ÂÂÂÂÂorder to bind it via the thermal DT code. This api can support
> multiple
> ÂÂÂÂÂinstances of cpufreq cooling devices.
> Â
> -ÂÂÂÂpolicy: CPUFreq policy.
> +ÂÂÂÂpolicy:
> + CPUFreq policy.
> Â
> -1.1.3 void cpufreq_cooling_unregister(struct thermal_cooling_device
> *cdev)
> +
> +ÂÂÂÂ::
> +
> + void cpufreq_cooling_unregister(struct
> thermal_cooling_device *cdev)
> Â
> ÂÂÂÂÂThis interface function unregisters the "thermal-cpufreq-%x"
> cooling device.
> Â
> ÂÂÂÂÂcdev: Cooling device pointer which has to be unregistered.
> Â
> Â2. Power models
> +===============
> Â
> ÂThe power API registration functions provide a simple power model
> for
> ÂCPUs.ÂÂThe current power is calculated as dynamic power (static
> power isn't
> @@ -65,9 +80,9 @@ For a given processor implementation the primary
> factors are:
> ÂÂÂvariation.ÂÂIn pathological cases this variation can be
> significant,
> ÂÂÂbut typically it is of a much lesser impact than the factors
> above.
> Â
> -A high level dynamic power consumption model may then be represented
> as:
> +A high level dynamic power consumption model may then be represented
> as::
> Â
> -Pdyn = f(run) * Voltage^2 * Frequency * Utilisation
> + Pdyn = f(run) * Voltage^2 * Frequency * Utilisation
> Â
> Âf(run) here represents the described execution behaviour and its
> Âresult has a units of Watts/Hz/Volt^2 (this often expressed in
> @@ -80,9 +95,9 @@ factors.ÂÂTherefore, in initial implementation that
> contribution is
> Ârepresented as a constant coefficient.ÂÂThis is a simplification
> Âconsistent with the relative contribution to overall power
> variation.
> Â
> -In this simplified representation our model becomes:
> +In this simplified representation our model becomes::
> Â
> -Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation
> + Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation
> Â
> ÂWhere `capacitance` is a constant that represents an indicative
> Ârunning time dynamic power coefficient in fundamental units of
> diff --git a/Documentation/thermal/exynos_thermal
> b/Documentation/thermal/exynos_thermal.rst
> similarity index 67%
> rename from Documentation/thermal/exynos_thermal
> rename to Documentation/thermal/exynos_thermal.rst
> index 9010c4416967..5bd556566c70 100644
> --- a/Documentation/thermal/exynos_thermal
> +++ b/Documentation/thermal/exynos_thermal.rst
> @@ -1,8 +1,11 @@
> +========================
> ÂKernel driver exynos_tmu
> -=================
> +========================
> Â
> ÂSupported chips:
> +
> Â* ARM SAMSUNG EXYNOS4, EXYNOS5 series of SoC
> +
> ÂÂÂDatasheet: Not publicly available
> Â
> ÂAuthors: Donggeun Kim <dg77.kim@xxxxxxxxxxx>
> @@ -19,32 +22,39 @@ Temperature can be taken from the temperature
> code.
> ÂThere are three equations converting from temperature to temperature
> code.
> Â
> ÂThe three equations are:
> -ÂÂ1. Two point trimming
> +ÂÂ1. Two point trimming::
> +
> Â Tc = (T - 25) * (TI2 - TI1) / (85 - 25) + TI1
> Â
> -ÂÂ2. One point trimming
> +ÂÂ2. One point trimming::
> +
> Â Tc = T + TI1 - 25
> Â
> -ÂÂ3. No trimming
> +ÂÂ3. No trimming::
> +
> Â Tc = T + 50
> Â
> -ÂÂTc: Temperature code, T: Temperature,
> -ÂÂTI1: Trimming info for 25 degree Celsius (stored at TRIMINFO
> register)
> +ÂÂTc:
> +ÂÂÂÂÂÂÂTemperature code, T: Temperature,
> +ÂÂTI1:
> +ÂÂÂÂÂÂÂTrimming info for 25 degree Celsius (stored at TRIMINFO
> register)
> ÂÂÂÂÂÂÂÂTemperature code measured at 25 degree Celsius which is
> unchanged
> -ÂÂTI2: Trimming info for 85 degree Celsius (stored at TRIMINFO
> register)
> +ÂÂTI2:
> +ÂÂÂÂÂÂÂTrimming info for 85 degree Celsius (stored at TRIMINFO
> register)
> ÂÂÂÂÂÂÂÂTemperature code measured at 85 degree Celsius which is
> unchanged
> Â
> ÂTMU(Thermal Management Unit) in EXYNOS4/5 generates interrupt
> Âwhen temperature exceeds pre-defined levels.
> ÂThe maximum number of configurable threshold is five.
> -The threshold levels are defined as follows:
> +The threshold levels are defined as follows::
> +
> ÂÂÂLevel_0: current temperature > trigger_level_0 + threshold
> ÂÂÂLevel_1: current temperature > trigger_level_1 + threshold
> ÂÂÂLevel_2: current temperature > trigger_level_2 + threshold
> ÂÂÂLevel_3: current temperature > trigger_level_3 + threshold
> Â
> -ÂÂThe threshold and each trigger_level are set
> -ÂÂthrough the corresponding registers.
> +The threshold and each trigger_level are set
> +through the corresponding registers.
> Â
> ÂWhen an interrupt occurs, this driver notify kernel thermal
> framework
> Âwith the function exynos_report_trigger.
> @@ -54,24 +64,27 @@ it can be used to synchronize the cooling action.
> ÂTMU driver description:
> Â-----------------------
> Â
> -The exynos thermal driver is structured as,
> +The exynos thermal driver is structured as::
> Â
> Â Kernel Core thermal
> framework
> Â (thermal_core.c, step_wise.c,
> cpu_cooling.c)
> Â ^
> Â |
> Â |
> -TMU configuration data -------> TMU DriverÂÂ<------> Exynos Core
> thermal wrapper
> -(exynos_tmu_data.c) ÂÂÂÂÂÂ(exynos_tmu.c) ÂÂÂ(exynos_th
> ermal_common.c)
> -(exynos_tmu_data.h) ÂÂÂÂÂÂ(exynos_tmu.h) ÂÂÂ(exynos_th
> ermal_common.h)
> +ÂÂTMU configuration data -----> TMU DriverÂÂ<----> Exynos Core
> thermal wrapper
> +ÂÂ(exynos_tmu_data.c) ÂÂÂÂÂÂ(exynos_tmu.c) ÂÂÂ(exynos_
> thermal_common.c)
> +ÂÂ(exynos_tmu_data.h) ÂÂÂÂÂÂ(exynos_tmu.h) ÂÂÂ(exynos_
> thermal_common.h)
> Â
> -a) TMU configuration data: This consist of TMU register
> offsets/bitfields
> +a) TMU configuration data:
> + This consist of TMU register offsets/bitfields
> Â described through structure exynos_tmu_registers.
> Also several
> Â other platform data (struct
> exynos_tmu_platform_data) members
> Â are used to configure the TMU.
> -b) TMU driver: This component initialises the TMU controller and
> sets different
> +b) TMU driver:
> + This component initialises the TMU controller and
> sets different
> Â thresholds. It invokes core thermal implementation
> with the call
> Â exynos_report_trigger.
> -c) Exynos Core thermal wrapper: This provides 3 wrapper function to
> use the
> +c) Exynos Core thermal wrapper:
> + This provides 3 wrapper function to use the
> Â Kernel core thermal framework. They are
> exynos_unregister_thermal,
> Â exynos_register_thermal and exynos_report_trigger.
> diff --git a/Documentation/thermal/exynos_thermal_emulation
> b/Documentation/thermal/exynos_thermal_emulation.rst
> similarity index 36%
> rename from Documentation/thermal/exynos_thermal_emulation
> rename to Documentation/thermal/exynos_thermal_emulation.rst
> index b15efec6ca28..c21d10838bc5 100644
> --- a/Documentation/thermal/exynos_thermal_emulation
> +++ b/Documentation/thermal/exynos_thermal_emulation.rst
> @@ -1,5 +1,6 @@
> -EXYNOS EMULATION MODE
> -========================
> +=====================
> +Exynos Emulation Mode
> +=====================
> Â
> ÂCopyright (C) 2012 Samsung Electronics
> Â
> @@ -8,46 +9,53 @@ Written by Jonghwa Lee <jonghwa3.lee@xxxxxxxxxxx>
> ÂDescription
> Â-----------
> Â
> -Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for
> thermal management unit.
> -Thermal emulation mode supports software debug for TMU's operation.
> User can set temperature
> -manually with software code and TMU will read current temperature
> from user value not from
> -sensor's value.
> +Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for
> thermal
> +management unit. Thermal emulation mode supports software debug for
> +TMU's operation. User can set temperature manually with software
> code
> +and TMU will read current temperature from user value not from
> sensor's
> +value.
> Â
> -Enabling CONFIG_THERMAL_EMULATION option will make this support
> available.
> -When it's enabled, sysfs node will be created as
> +Enabling CONFIG_THERMAL_EMULATION option will make this support
> +available. When it's enabled, sysfs node will be created as
> Â/sys/devices/virtual/thermal/thermal_zone'zone id'/emul_temp.
> Â
> -The sysfs node, 'emul_node', will contain value 0 for the initial
> state. When you input any
> -temperature you want to update to sysfs node, it automatically
> enable emulation mode and
> -current temperature will be changed into it.
> -(Exynos also supports user changeable delay time which would be used
> to delay of
> - changing temperature. However, this node only uses same delay of
> real sensing time, 938us.)
> +The sysfs node, 'emul_node', will contain value 0 for the initial
> state.
> +When you input any temperature you want to update to sysfs node, it
> +automatically enable emulation mode and current temperature will be
> +changed into it.
> Â
> -Exynos emulation mode requires synchronous of value changing and
> enabling. It means when you
> -want to update the any value of delay or next temperature, then you
> have to enable emulation
> -mode at the same time. (Or you have to keep the mode enabling.) If
> you don't, it fails to
> -change the value to updated one and just use last succeessful value
> repeatedly. That's why
> -this node gives users the right to change termerpature only. Just
> one interface makes it more
> -simply to use.
> +(Exynos also supports user changeable delay time which would be used
> to
> +delay of changing temperature. However, this node only uses same
> delay
> +of real sensing time, 938us.)
> +
> +Exynos emulation mode requires synchronous of value changing and
> +enabling. It means when you want to update the any value of delay or
> +next temperature, then you have to enable emulation mode at the same
> +time. (Or you have to keep the mode enabling.) If you don't, it
> fails to
> +change the value to updated one and just use last succeessful value
> +repeatedly. That's why this node gives users the right to change
> +termerpature only. Just one interface makes it more simply to use.
> Â
> ÂDisabling emulation mode only requires writing value 0 to sysfs
> node.
> Â
> +::
> Â
> -TEMP 120 |
> +
> +ÂÂTEMP 120 |
> Â ÂÂÂÂ|
> Â 100 |
> Â ÂÂÂÂ|
> Â Â80 |
> - ÂÂÂÂ| ÂÂÂÂÂ Â Â+-----------
> - Â60 |ÂÂÂÂÂÂ ÂÂÂÂÂ Â| ÂÂÂÂ|
> - ÂÂÂÂ| ÂÂÂÂÂÂÂÂÂÂÂ+-------------|ÂÂÂÂÂÂÂÂÂÂ|
> + ÂÂÂÂ| Â+-----------
> + Â60 |ÂÂÂÂÂÂ Â| ÂÂÂÂ|
> + ÂÂÂÂ| ÂÂÂ+-------------|ÂÂÂÂÂÂÂÂÂÂ|
> Â Â40 |ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ Â|ÂÂÂÂÂÂÂÂÂÂ|
> - ÂÂÂÂ| ÂÂÂ| ÂÂÂÂÂ Â|ÂÂÂÂÂÂÂÂÂÂ|
> - Â20 | ÂÂÂ| ÂÂÂÂÂ Â|ÂÂÂÂÂÂÂÂÂÂ+-
> ---------
> - ÂÂÂÂ| Â ÂÂÂ| ÂÂÂÂÂ Â|ÂÂÂÂÂÂÂÂÂÂ|
> ÂÂÂÂÂÂÂÂÂÂ|
> + ÂÂÂÂ| ÂÂÂ| Â|ÂÂÂÂÂÂÂÂÂÂ|
> + Â20 | ÂÂÂ| Â|ÂÂÂÂÂÂÂÂÂÂ+----
> ------
> + ÂÂÂÂ| ÂÂÂ| Â|ÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂ
> ÂÂÂÂ|
> Â ÂÂ0
> |______________|_____________|__________|__________|_________
> - ÂÂÂA ÂÂÂÂ ÂA ÂÂÂÂA ÂÂÂ
> ÂÂÂÂÂÂÂAÂÂÂÂÂTIME
> + ÂÂÂA ÂA ÂÂÂÂA Â
> ÂÂÂÂÂÂAÂÂÂÂÂTIME
> Â ÂÂÂ|<----->| Â|<----->|ÂÂ|<----->| ÂÂÂ
> ÂÂÂÂ|
> Â ÂÂÂ| 938us |ÂÂ Â| Â|ÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ
> ÂÂÂ|
> -emulationÂÂÂÂ:ÂÂ0ÂÂ50 ÂÂÂ|ÂÂ Â70ÂÂÂÂÂÂ|ÂÂ20ÂÂÂÂÂÂ|ÂÂÂÂ
> ÂÂÂÂÂÂ0
> -current temp :ÂÂÂsensorÂÂÂ50 Â70ÂÂÂÂÂÂÂÂÂ20 ÂÂ
> ÂÂÂÂsensor
> +ÂÂemulationÂÂÂ: 0ÂÂ50 ÂÂÂ|ÂÂ Â70ÂÂÂÂÂÂ|ÂÂ20ÂÂÂÂÂÂ|ÂÂÂÂ
> ÂÂÂÂÂÂ0
> +ÂÂcurrent temp:ÂÂÂsensorÂÂÂ50 Â70ÂÂÂÂÂÂÂÂÂ20 Â
> ÂÂÂÂÂsensor
> diff --git a/Documentation/thermal/index.rst
> b/Documentation/thermal/index.rst
> new file mode 100644
> index 000000000000..8c1c00146cad
> --- /dev/null
> +++ b/Documentation/thermal/index.rst
> @@ -0,0 +1,18 @@
> +:orphan:
> +
> +=======
> +Thermal
> +=======
> +
> +.. toctree::
> +ÂÂÂ:maxdepth: 1
> +
> +ÂÂÂcpu-cooling-api
> +ÂÂÂsysfs-api
> +ÂÂÂpower_allocator
> +
> +ÂÂÂexynos_thermal
> +ÂÂÂexynos_thermal_emulation
> +ÂÂÂintel_powerclamp
> +ÂÂÂnouveau_thermal
> +ÂÂÂx86_pkg_temperature_thermal
> diff --git a/Documentation/thermal/intel_powerclamp.txt
> b/Documentation/thermal/intel_powerclamp.rst
> similarity index 76%
> rename from Documentation/thermal/intel_powerclamp.txt
> rename to Documentation/thermal/intel_powerclamp.rst
> index b5df21168fbc..3f6dfb0b3ea6 100644
> --- a/Documentation/thermal/intel_powerclamp.txt
> +++ b/Documentation/thermal/intel_powerclamp.rst
> @@ -1,10 +1,13 @@
> - Â=======================
> - ÂINTEL POWERCLAMP DRIVER
> - Â=======================
> -By: Arjan van de Ven <arjan@xxxxxxxxxxxxxxx>
> -ÂÂÂÂJacob Pan <jacob.jun.pan@xxxxxxxxxxxxxxx>
> +=======================
> +Intel Powerclamp Driver
> +=======================
> +
> +By:
> +ÂÂ- Arjan van de Ven <arjan@xxxxxxxxxxxxxxx>
> +ÂÂ- Jacob Pan <jacob.jun.pan@xxxxxxxxxxxxxxx>
> +
> +.. Contents:
> Â
> -Contents:
> Â (*) Introduction
> Â ÂÂÂÂ- Goals and Objectives
> Â
> @@ -23,7 +26,6 @@ Contents:
> Â ÂÂÂÂ- Generic Thermal Layer (sysfs)
> Â ÂÂÂÂ- Kernel APIs (TBD)
> Â
> -============
> ÂINTRODUCTION
> Â============
> Â
> @@ -47,7 +49,6 @@ scalability, and user experience. In many cases,
> clear advantage is
> Âshown over taking the CPU offline or modulating the CPU clock.
> Â
> Â
> -===================
> ÂTHEORY OF OPERATION
> Â===================
> Â
> @@ -57,11 +58,12 @@ Idle Injection
> ÂOn modern Intel processors (Nehalem or later), package level C-state
> Âresidency is available in MSRs, thus also available to the kernel.
> Â
> -These MSRs are:
> -ÂÂÂÂÂÂ#define MSR_PKG_C2_RESIDENCY 0x60D
> -ÂÂÂÂÂÂ#define MSR_PKG_C3_RESIDENCY 0x3F8
> -ÂÂÂÂÂÂ#define MSR_PKG_C6_RESIDENCY 0x3F9
> -ÂÂÂÂÂÂ#define MSR_PKG_C7_RESIDENCY 0x3FA
> +These MSRs are::
> +
> +ÂÂÂÂÂÂ#define MSR_PKG_C2_RESIDENCYÂÂÂÂÂÂ0x60D
> +ÂÂÂÂÂÂ#define MSR_PKG_C3_RESIDENCYÂÂÂÂÂÂ0x3F8
> +ÂÂÂÂÂÂ#define MSR_PKG_C6_RESIDENCYÂÂÂÂÂÂ0x3F9
> +ÂÂÂÂÂÂ#define MSR_PKG_C7_RESIDENCYÂÂÂÂÂÂ0x3FA
> Â
> ÂIf the kernel can also inject idle time to the system, then a
> Âclosed-loop control system can be established that manages package
> @@ -96,19 +98,21 @@ are not masked. Tests show that the extra wakeups
> from scheduler tick
> Âhave a dramatic impact on the effectiveness of the powerclamp driver
> Âon large scale systems (Westmere system with 80 processors).
> Â
> -CPU0
> - ÂÂ____________ÂÂÂÂÂÂÂÂÂÂ____________
> -kidle_inject/0ÂÂÂ|ÂÂÂsleepÂÂÂÂ|ÂÂmwait |ÂÂsleepÂÂÂÂÂ|
> - _________|ÂÂÂÂÂÂÂÂÂÂÂÂ|________|ÂÂÂÂÂÂÂÂÂÂÂÂ|_______
> - ÂÂÂÂÂÂÂduration
> -CPU1
> - ÂÂ____________ÂÂÂÂÂÂÂÂÂÂ____________
> -kidle_inject/1ÂÂÂ|ÂÂÂsleepÂÂÂÂ|ÂÂmwait |ÂÂsleepÂÂÂÂÂ|
> - _________|ÂÂÂÂÂÂÂÂÂÂÂÂ|________|ÂÂÂÂÂÂÂÂÂÂÂÂ|_______
> - ÂÂÂÂÂÂ^
> - ÂÂÂÂÂÂ|
> - ÂÂÂÂÂÂ|
> - ÂÂÂÂÂÂroundup(jiffies, interval)
> +::
> +
> +ÂÂCPU0
> + ÂÂÂÂ____________ÂÂÂÂÂÂÂÂÂÂ____________
> +ÂÂkidle_inject/0ÂÂÂ|ÂÂÂsleepÂÂÂÂ|ÂÂmwait |ÂÂsleepÂÂÂÂÂ|
> + ÂÂ_________|ÂÂÂÂÂÂÂÂÂÂÂÂ|________|ÂÂÂÂÂÂÂÂÂÂÂÂ|_______
> + Âduration
> +ÂÂCPU1
> + ÂÂÂÂ____________ÂÂÂÂÂÂÂÂÂÂ____________
> +ÂÂkidle_inject/1ÂÂÂ|ÂÂÂsleepÂÂÂÂ|ÂÂmwait |ÂÂsleepÂÂÂÂÂ|
> + ÂÂ_________|ÂÂÂÂÂÂÂÂÂÂÂÂ|________|ÂÂÂÂÂÂÂÂÂÂÂÂ|_______
> + ^
> + |
> + |
> + roundup(jiffies, interval)
> Â
> ÂOnly one CPU is allowed to collect statistics and update global
> Âcontrol parameters. This CPU is referred to as the controlling CPU
> in
> @@ -148,7 +152,7 @@ b) determine the amount of compensation needed at
> each target ratio
> Â
> ÂCompensation to each target ratio consists of two parts:
> Â
> -ÂÂÂÂÂÂÂÂa) steady state error compensation
> + a) steady state error compensation
> Â This is to offset the error occurring when the system can
> Â enter idle without extra wakeups (such as external
> interrupts).
> Â
> @@ -158,41 +162,42 @@ Compensation to each target ratio consists of
> two parts:
> Â slowing down CPU activities.
> Â
> ÂA debugfs file is provided for the user to examine compensation
> -progress and results, such as on a Westmere system.
> -[jacob@nex01 ~]$ cat
> -/sys/kernel/debug/intel_powerclamp/powerclamp_calib
> -controlling cpu: 0
> -pct confidence steady dynamic (compensation)
> -0 0 0 0
> -1 1 0 0
> -2 1 1 0
> -3 3 1 0
> -4 3 1 0
> -5 3 1 0
> -6 3 1 0
> -7 3 1 0
> -8 3 1 0
> -...
> -30 3 2 0
> -31 3 2 0
> -32 3 1 0
> -33 3 2 0
> -34 3 1 0
> -35 3 2 0
> -36 3 1 0
> -37 3 2 0
> -38 3 1 0
> -39 3 2 0
> -40 3 3 0
> -41 3 1 0
> -42 3 2 0
> -43 3 1 0
> -44 3 1 0
> -45 3 2 0
> -46 3 3 0
> -47 3 0 0
> -48 3 2 0
> -49 3 3 0
> +progress and results, such as on a Westmere system::
> +
> +ÂÂ[jacob@nex01 ~]$ cat
> +ÂÂ/sys/kernel/debug/intel_powerclamp/powerclamp_calib
> +ÂÂcontrolling cpu: 0
> +ÂÂpct confidence steady dynamic (compensation)
> +ÂÂ0ÂÂÂÂÂÂÂ0ÂÂÂÂÂÂÂ0ÂÂÂÂÂÂÂ0
> +ÂÂ1ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0ÂÂÂÂÂÂÂ0
> +ÂÂ2ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ3ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ4ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ5ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ6ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ7ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ8ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ...
> +ÂÂ30ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ31ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ32ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ33ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ34ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ35ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ36ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ37ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ38ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ39ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ40ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ0
> +ÂÂ41ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ42ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ43ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ44ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ1ÂÂÂÂÂÂÂ0
> +ÂÂ45ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ46ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ0
> +ÂÂ47ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ0ÂÂÂÂÂÂÂ0
> +ÂÂ48ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ2ÂÂÂÂÂÂÂ0
> +ÂÂ49ÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ3ÂÂÂÂÂÂÂ0
> Â
> ÂCalibration occurs during runtime. No offline method is available.
> ÂSteady state compensation is used only when confidence levels of all
> @@ -217,9 +222,8 @@ keeps track of clamping kernel threads, even
> after they are migrated
> Âto other CPUs, after a CPU offline event.
> Â
> Â
> -=====================
> ÂPerformance Analysis
> -=====================
> +====================
> ÂThis section describes the general performance data collected on
> Âmultiple systems, including Westmere (80P) and Ivy Bridge (4P, 8P).
> Â
> @@ -257,16 +261,15 @@ achieve up to 40% better performance per watt.
> (measured by a spin
> Âcounter summed over per CPU counting threads spawned for all running
> ÂCPUs).
> Â
> -====================
> ÂUsage and Interfaces
> Â====================
> ÂThe powerclamp driver is registered to the generic thermal layer as
> a
> -cooling device. Currently, itâs not bound to any thermal zones.
> +cooling device. Currently, itâs not bound to any thermal zones::
> Â
> -jacob@chromoly:/sys/class/thermal/cooling_device14$ grep . *
> -cur_state:0
> -max_state:50
> -type:intel_powerclamp
> +ÂÂjacob@chromoly:/sys/class/thermal/cooling_device14$ grep . *
> +ÂÂcur_state:0
> +ÂÂmax_state:50
> +ÂÂtype:intel_powerclamp
> Â
> Âcur_state allows user to set the desired idle percentage. Writing 0
> to
> Âcur_state will stop idle injection. Writing a value between 1 and
> @@ -278,9 +281,9 @@ cur_state returns value -1 instead of 0 which is
> to avoid confusing
> Â100% busy state with the disabled state.
> Â
> ÂExample usage:
> -- To inject 25% idle time
> -$ sudo sh -c "echo 25 >
> /sys/class/thermal/cooling_device80/cur_state
> -"
> +- To inject 25% idle time::
> +
> + $ sudo sh -c "echo 25 >
> /sys/class/thermal/cooling_device80/cur_state
> Â
> ÂIf the system is not busy and has more than 25% idle time already,
> Âthen the powerclamp driver will not start idle injection. Using Top
> @@ -292,23 +295,23 @@ idle time is accounted as normal idle in that
> common code path is
> Âtaken as the idle task.
> Â
> ÂIn this example, 24.1% idle is shown. This helps the system admin or
> -user determine the cause of slowdown, when a powerclamp driver is in
> action.
> +user determine the cause of slowdown, when a powerclamp driver is in
> action::
> Â
> Â
> -Tasks: 197 total,ÂÂÂ1 running, 196 sleeping,ÂÂÂ0 stopped,ÂÂÂ0 zombie
> -Cpu(s): 71.2%us,ÂÂ4.7%sy,ÂÂ0.0%ni,
> 24.1%id,ÂÂ0.0%wa,ÂÂ0.0%hi,ÂÂ0.0%si,ÂÂ0.0%st
> -Mem:ÂÂÂ3943228k total,ÂÂ1689632k used,ÂÂ2253596k free,ÂÂÂÂ74960k
> buffers
> -Swap:ÂÂ4087804k total,ÂÂÂÂÂÂÂÂ0k used,ÂÂ4087804k free,ÂÂÂ945336k
> cached
> +ÂÂTasks: 197 total,ÂÂÂ1 running, 196 sleeping,ÂÂÂ0 stopped,ÂÂÂ0
> zombie
> +ÂÂCpu(s): 71.2%us,ÂÂ4.7%sy,ÂÂ0.0%ni,
> 24.1%id,ÂÂ0.0%wa,ÂÂ0.0%hi,ÂÂ0.0%si,ÂÂ0.0%st
> +ÂÂMem:ÂÂÂ3943228k total,ÂÂ1689632k used,ÂÂ2253596k free,ÂÂÂÂ74960k
> buffers
> +ÂÂSwap:ÂÂ4087804k total,ÂÂÂÂÂÂÂÂ0k used,ÂÂ4087804k free,ÂÂÂ945336k
> cached
> Â
> -ÂÂPID USERÂÂÂÂÂÂPRÂÂNIÂÂVIRTÂÂRESÂÂSHR S %CPU %MEMÂÂÂÂTIME+ÂÂCOMMAND
> - 3352 jacobÂÂÂÂÂ20ÂÂÂ0ÂÂ262mÂÂ644ÂÂ428 SÂÂ286ÂÂ0.0ÂÂÂ0:17.16 spin
> - 3341 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.62
> kidle_inject/0
> - 3344 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.60
> kidle_inject/3
> - 3342 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.61
> kidle_inject/1
> - 3343 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.60
> kidle_inject/2
> - 2935 jacobÂÂÂÂÂ20ÂÂÂ0ÂÂ696m 125mÂÂ35m SÂÂÂÂ5ÂÂ3.3ÂÂÂ0:31.11 firefox
> - 1546 rootÂÂÂÂÂÂ20ÂÂÂ0ÂÂ158mÂÂ20m 6640 SÂÂÂÂ3ÂÂ0.5ÂÂÂ0:26.97 Xorg
> - 2100 jacobÂÂÂÂÂ20ÂÂÂ0 1223mÂÂ88mÂÂ30m SÂÂÂÂ3ÂÂ2.3ÂÂÂ0:23.68 compiz
> +ÂÂÂÂPID USERÂÂÂÂÂÂPRÂÂNIÂÂVIRTÂÂRESÂÂSHR S %CPU
> %MEMÂÂÂÂTIME+ÂÂCOMMAND
> +ÂÂÂ3352 jacobÂÂÂÂÂ20ÂÂÂ0ÂÂ262mÂÂ644ÂÂ428 SÂÂ286ÂÂ0.0ÂÂÂ0:17.16 spin
> +ÂÂÂ3341 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.62
> kidle_inject/0
> +ÂÂÂ3344 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.60
> kidle_inject/3
> +ÂÂÂ3342 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.61
> kidle_inject/1
> +ÂÂÂ3343 rootÂÂÂÂÂ-51ÂÂÂ0ÂÂÂÂÂ0ÂÂÂÂ0ÂÂÂÂ0 DÂÂÂ25ÂÂ0.0ÂÂÂ0:01.60
> kidle_inject/2
> +ÂÂÂ2935 jacobÂÂÂÂÂ20ÂÂÂ0ÂÂ696m 125mÂÂ35m SÂÂÂÂ5ÂÂ3.3ÂÂÂ0:31.11
> firefox
> +ÂÂÂ1546 rootÂÂÂÂÂÂ20ÂÂÂ0ÂÂ158mÂÂ20m 6640 SÂÂÂÂ3ÂÂ0.5ÂÂÂ0:26.97 Xorg
> +ÂÂÂ2100 jacobÂÂÂÂÂ20ÂÂÂ0 1223mÂÂ88mÂÂ30m SÂÂÂÂ3ÂÂ2.3ÂÂÂ0:23.68
> compiz
> Â
> ÂTests have shown that by using the powerclamp driver as a cooling
> Âdevice, a PID based userspace thermal controller can manage to
> diff --git a/Documentation/thermal/nouveau_thermal
> b/Documentation/thermal/nouveau_thermal.rst
> similarity index 64%
> rename from Documentation/thermal/nouveau_thermal
> rename to Documentation/thermal/nouveau_thermal.rst
> index 6e17a11efcb0..37255fd6735d 100644
> --- a/Documentation/thermal/nouveau_thermal
> +++ b/Documentation/thermal/nouveau_thermal.rst
> @@ -1,13 +1,15 @@
> +=====================
> ÂKernel driver nouveau
> -===================
> +=====================
> Â
> ÂSupported chips:
> +
> Â* NV43+
> Â
> ÂAuthors: Martin Peres (mupuf) <martin.peres@xxxxxxx>
> Â
> ÂDescription
> ----------
> +-----------
> Â
> ÂThis driver allows to read the GPU core temperature, drive the GPU
> fan and
> Âset temperature alarms.
> @@ -19,20 +21,25 @@ interface is likely not to work. This document
> may then not cover your situation
> Âentirely.
> Â
> ÂTemperature management
> ---------------------
> +----------------------
> Â
> ÂTemperature is exposed under as a read-only HWMON attribute
> temp1_input.
> Â
> ÂIn order to protect the GPU from overheating, Nouveau supports 4
> configurable
> Âtemperature thresholds:
> Â
> - * Fan_boost: Fan speed is set to 100% when reaching this
> temperature;
> - * Downclock: The GPU will be downclocked to reduce its power
> dissipation;
> - * Critical: The GPU is put on hold to further lower power
> dissipation;
> - * Shutdown: Shut the computer down to protect your GPU.
> + * Fan_boost:
> + Fan speed is set to 100% when reaching this temperature;
> + * Downclock:
> + The GPU will be downclocked to reduce its power dissipation;
> + * Critical:
> + The GPU is put on hold to further lower power dissipation;
> + * Shutdown:
> + Shut the computer down to protect your GPU.
> Â
> -WARNING: Some of these thresholds may not be used by Nouveau
> depending
> -on your chipset.
> +WARNING:
> + Some of these thresholds may not be used by Nouveau
> depending
> + on your chipset.
> Â
> ÂThe default value for these thresholds comes from the GPU's vbios.
> These
> Âthresholds can be configured thanks to the following HWMON
> attributes:
> @@ -46,19 +53,24 @@ NOTE: Remember that the values are stored as
> milli degrees Celsius. Don't forget
> Âto multiply!
> Â
> ÂFan management
> -------------
> +--------------
> Â
> ÂNot all cards have a drivable fan. If you do, then the following
> HWMON
> Âattributes should be available:
> Â
> - * pwm1_enable: Current fan management mode (NONE, MANUAL or AUTO);
> - * pwm1: Current PWM value (power percentage);
> - * pwm1_min: The minimum PWM speed allowed;
> - * pwm1_max: The maximum PWM speed allowed (bypassed when hitting
> Fan_boost);
> + * pwm1_enable:
> + Current fan management mode (NONE, MANUAL or AUTO);
> + * pwm1:
> + Current PWM value (power percentage);
> + * pwm1_min:
> + The minimum PWM speed allowed;
> + * pwm1_max:
> + The maximum PWM speed allowed (bypassed when hitting
> Fan_boost);
> Â
> ÂYou may also have the following attribute:
> Â
> - * fan1_input: Speed in RPM of your fan.
> + * fan1_input:
> + Speed in RPM of your fan.
> Â
> ÂYour fan can be driven in different modes:
> Â
> @@ -66,14 +78,16 @@ Your fan can be driven in different modes:
> Â * 1: The fan can be driven in manual (use pwm1 to change the
> speed);
> Â * 2; The fan is driven automatically depending on the temperature.
> Â
> -NOTE: Be sure to use the manual mode if you want to drive the fan
> speed manually
> +NOTE:
> +ÂÂBe sure to use the manual mode if you want to drive the fan speed
> manually
> Â
> -NOTE2: When operating in manual mode outside the vbios-defined
> -[PWM_min, PWM_max] range, the reported fan speed (RPM) may not be
> accurate
> -depending on your hardware.
> +NOTE2:
> +ÂÂWhen operating in manual mode outside the vbios-defined
> +ÂÂ[PWM_min, PWM_max] range, the reported fan speed (RPM) may not be
> accurate
> +ÂÂdepending on your hardware.
> Â
> ÂBug reports
> ----------
> +-----------
> Â
> ÂThermal management on Nouveau is new and may not work on all cards.
> If you have
> Âinquiries, please ping mupuf on IRC (#nouveau, freenode).
> diff --git a/Documentation/thermal/power_allocator.txt
> b/Documentation/thermal/power_allocator.rst
> similarity index 74%
> rename from Documentation/thermal/power_allocator.txt
> rename to Documentation/thermal/power_allocator.rst
> index 9fb0ff06dca9..67b6a3297238 100644
> --- a/Documentation/thermal/power_allocator.txt
> +++ b/Documentation/thermal/power_allocator.rst
> @@ -1,3 +1,4 @@
> +=================================
> ÂPower allocator governor tunables
> Â=================================
> Â
> @@ -25,36 +26,36 @@ temperature as the control input and power as the
> controlled output:
> ÂÂÂÂÂP_max = k_p * e + k_i * err_integral + k_d * diff_err +
> sustainable_power
> Â
> Âwhere
> -ÂÂÂÂe = desired_temperature - current_temperature
> -ÂÂÂÂerr_integral is the sum of previous errors
> -ÂÂÂÂdiff_err = e - previous_error
> +ÂÂÂ-ÂÂe = desired_temperature - current_temperature
> +ÂÂÂ-ÂÂerr_integral is the sum of previous errors
> +ÂÂÂ-ÂÂdiff_err = e - previous_error
> Â
> -It is similar to the one depicted below:
> +It is similar to the one depicted below::
> Â
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂk_d
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|
> -current_tempÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂv
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ+----------+ÂÂÂ+---+
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ+----->| diff_err |-->| X |------+
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂ+----------+ÂÂÂ+---+ÂÂÂÂÂÂ|
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂtdpÂÂÂÂÂÂÂÂac
> tor
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂk_iÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂget_reque
> sted_power()
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂ
> ÂÂÂ|
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂ
> ÂÂÂ| ...
> -ÂÂÂÂÂvÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂvÂÂÂÂÂÂÂÂvÂÂÂÂÂÂÂvÂÂÂÂÂÂÂÂvÂÂ
> ÂÂÂv
> -ÂÂÂ+---+ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂ+-------+ÂÂÂÂÂÂ+---+ÂÂÂÂ+---+ÂÂÂ+---+ÂÂÂ+-----
> -----+
> -ÂÂÂ| S |-------+----->| sum e |----->| X |--->| S |-->| S |
> -->|powerÂÂÂÂÂ|
> -ÂÂÂ+---+ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂ+-------+ÂÂÂÂÂÂ+---+ÂÂÂÂ+---+ÂÂÂ+---
> +ÂÂÂ|allocation|
> -ÂÂÂÂÂ^ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ^ÂÂÂÂÂÂÂÂÂÂÂÂÂ+-----
> -----+
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂ
> ÂÂÂ|
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ+---
> +ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂ|
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂ+------->| X |-------------------
> +ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂvÂÂÂÂÂv
> -ÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ+---+ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂgranted
> performance
> -desired_temperatureÂÂÂÂÂÂÂ^
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂk_po/k_pu
> + ÂÂÂÂÂÂk_d
> + ÂÂÂÂÂÂÂ|
> +ÂÂcurrent_tempÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂv
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ+----------+ÂÂÂ+---+
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ+----->| diff_err |-->| X |------+
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂ+----------+ÂÂÂ+---+ÂÂÂÂÂÂ|
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂtdpÂÂÂÂÂÂÂÂac
> tor
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂk_iÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂget_reque
> sted_power()
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂ
> ÂÂÂ|
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ|ÂÂ
> ÂÂÂ| ...
> +ÂÂÂÂÂÂÂvÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂvÂÂÂÂÂÂÂÂvÂÂÂÂÂÂÂvÂÂÂÂÂÂÂÂvÂÂ
> ÂÂÂv
> +ÂÂÂÂÂ+---+ÂÂÂÂÂ|ÂÂÂÂÂÂ+-------+ÂÂÂÂÂÂ+---+ÂÂÂÂ+---+ÂÂÂ+---+ÂÂÂ+-----
> -----+
> +ÂÂÂÂÂ| S |-----+----->| sum e |----->| X |--->| S |-->| S |
> -->|powerÂÂÂÂÂ|
> +ÂÂÂÂÂ+---+ÂÂÂÂÂ|ÂÂÂÂÂÂ+-------+ÂÂÂÂÂÂ+---+ÂÂÂÂ+---+ÂÂÂ+---
> +ÂÂÂ|allocation|
> +ÂÂÂÂÂÂÂ^ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ^ÂÂÂÂÂÂÂÂÂÂÂÂÂ+-----
> -----+
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂ
> ÂÂÂ|
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂ+---
> +ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ|ÂÂÂÂÂ|
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂ+------->| X |-------------------
> +ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂvÂÂÂÂÂv
> +ÂÂÂÂÂÂÂ|ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ+---+ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂgranted
> performance
> +ÂÂdesired_temperatureÂÂÂÂÂ^
> + ÂÂ|
> + ÂÂ|
> + ÂÂÂÂÂÂk_po/k_pu
> Â
> ÂSustainable power
> Â-----------------
> @@ -73,7 +74,7 @@ is typically 2000mW, while on a 10" tablet is
> around 4500mW (may vary
> Âdepending on screen size).
> Â
> ÂIf you are using device tree, do add it as a property of the
> -thermal-zone.ÂÂFor example:
> +thermal-zone.ÂÂFor example::
> Â
> Â thermal-zones {
> Â soc_thermal {
> @@ -85,7 +86,7 @@ thermal-zone.ÂÂFor example:
> ÂInstead, if the thermal zone is registered from the platform code,
> pass a
> Â`thermal_zone_params` that has a `sustainable_power`.ÂÂIf no
> Â`thermal_zone_params` were being passed, then something like below
> -will suffice:
> +will suffice::
> Â
> Â static const struct thermal_zone_params tz_params = {
> Â .sustainable_power = 3500,
> @@ -112,18 +113,18 @@ available capacity at a low temperature.ÂÂOn
> the other hand, a high
> Âvalue of `k_pu` will result in the governor granting very high power
> Âwhile temperature is low, and may lead to temperature overshooting.
> Â
> -The default value for `k_pu` is:
> +The default value for `k_pu` is::
> Â
> ÂÂÂÂÂ2 * sustainable_power / (desired_temperature - switch_on_temp)
> Â
> ÂThis means that at `switch_on_temp` the output of the controller's
> Âproportional term will be 2 * `sustainable_power`.ÂÂThe default
> value
> -for `k_po` is:
> +for `k_po` is::
> Â
> ÂÂÂÂÂsustainable_power / (desired_temperature - switch_on_temp)
> Â
> ÂFocusing on the proportional and feed forward values of the PID
> -controller equation we have:
> +controller equation we have::
> Â
> ÂÂÂÂÂP_max = k_p * e + sustainable_power
> Â
> @@ -134,21 +135,23 @@ is the desired one, then the proportional
> component is zero and
> Âthermal equilibrium under constant load.ÂÂ`sustainable_power` is
> only
> Âan estimate, which is the reason for closed-loop control such as
> this.
> Â
> -Expanding `k_pu` we get:
> +Expanding `k_pu` we get::
> +
> ÂÂÂÂÂP_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) +
> -ÂÂÂÂÂÂÂÂsustainable_power
> + sustainable_power
> Â
> -where
> -ÂÂÂÂT_set is the desired temperature
> -ÂÂÂÂT is the current temperature
> -ÂÂÂÂT_on is the switch on temperature
> +where:
> +
> +ÂÂÂÂ- T_set is the desired temperature
> +ÂÂÂÂ- T is the current temperature
> +ÂÂÂÂ- T_on is the switch on temperature
> Â
> ÂWhen the current temperature is the switch_on temperature, the above
> -formula becomes:
> +formula becomes::
> Â
> ÂÂÂÂÂP_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on)
> +
> -ÂÂÂÂÂÂÂÂsustainable_power = 2 * sustainable_power +
> sustainable_power =
> -ÂÂÂÂÂÂÂÂ3 * sustainable_power
> + sustainable_power = 2 * sustainable_power +
> sustainable_power =
> + 3 * sustainable_power
> Â
> ÂTherefore, the proportional term alone linearly decreases power from
> Â3 * `sustainable_power` to `sustainable_power` as the temperature
> @@ -178,11 +181,18 @@ Cooling device power API
> ÂCooling devices controlled by this governor must supply the
> additional
> Â"power" API in their `cooling_device_ops`.ÂÂIt consists on three
> ops:
> Â
> -1. int get_requested_power(struct thermal_cooling_device *cdev,
> - struct thermal_zone_device *tz, u32 *power);
> -@cdev: The `struct thermal_cooling_device` pointer
> -@tz: thermal zone in which we are currently operating
> -@power: pointer in which to store the calculated power
> +1. ::
> +
> +ÂÂÂÂint get_requested_power(struct thermal_cooling_device *cdev,
> + ÂÂÂÂstruct thermal_zone_device *tz, u32
> *power);
> +
> +
> +@cdev:
> + The `struct thermal_cooling_device` pointer
> +@tz:
> + thermal zone in which we are currently operating
> +@power:
> + pointer in which to store the calculated power
> Â
> Â`get_requested_power()` calculates the power requested by the device
> Âin milliwatts and stores it in @power .ÂÂIt should return 0 on
> @@ -190,23 +200,37 @@ success, -E* on failure.ÂÂThis is currently
> used by the power
> Âallocator governor to calculate how much power to give to each
> cooling
> Âdevice.
> Â
> -2. int state2power(struct thermal_cooling_device *cdev, struct
> -ÂÂÂÂÂÂÂÂthermal_zone_device *tz, unsigned long state, u32 *power);
> -@cdev: The `struct thermal_cooling_device` pointer
> -@tz: thermal zone in which we are currently operating
> -@state: A cooling device state
> -@power: pointer in which to store the equivalent power
> +2. ::
> +
> + int state2power(struct thermal_cooling_device *cdev, struct
> + thermal_zone_device *tz, unsigned long
> state,
> + u32 *power);
> +
> +@cdev:
> + The `struct thermal_cooling_device` pointer
> +@tz:
> + thermal zone in which we are currently operating
> +@state:
> + A cooling device state
> +@power:
> + pointer in which to store the equivalent power
> Â
> ÂConvert cooling device state @state into power consumption in
> Âmilliwatts and store it in @power.ÂÂIt should return 0 on success,
> -E*
> Âon failure.ÂÂThis is currently used by thermal core to calculate the
> Âmaximum power that an actor can consume.
> Â
> -3. int power2state(struct thermal_cooling_device *cdev, u32 power,
> - unsigned long *state);
> -@cdev: The `struct thermal_cooling_device` pointer
> -@power: power in milliwatts
> -@state: pointer in which to store the resulting state
> +3. ::
> +
> + int power2state(struct thermal_cooling_device *cdev, u32
> power,
> + unsigned long *state);
> +
> +@cdev:
> + The `struct thermal_cooling_device` pointer
> +@power:
> + power in milliwatts
> +@state:
> + pointer in which to store the resulting state
> Â
> ÂCalculate a cooling device state that would make the device consume
> at
> Âmost @power mW and store it in @state.ÂÂIt should return 0 on
> success,
> diff --git a/Documentation/thermal/sysfs-api.txt
> b/Documentation/thermal/sysfs-api.rst
> similarity index 66%
> rename from Documentation/thermal/sysfs-api.txt
> rename to Documentation/thermal/sysfs-api.rst
> index c3fa500df92c..e4930761d3e5 100644
> --- a/Documentation/thermal/sysfs-api.txt
> +++ b/Documentation/thermal/sysfs-api.rst
> @@ -1,3 +1,4 @@
> +===================================
> ÂGeneric Thermal Sysfs driver How To
> Â===================================
> Â
> @@ -9,6 +10,7 @@ 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
> @@ -25,59 +27,90 @@ 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
> +- `[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
> *type,
> - int trips, int mask, void *devdata,
> - struct thermal_zone_device_ops *ops,
> - const struct thermal_zone_params *tzp,
> - int passive_delay, int polling_delay))
> +---------------------------------
> +
> +ÂÂÂÂ::
> +
> + struct thermal_zone_device
> + *thermal_zone_device_register(char *type,
> + ÂÂÂÂÂÂint trips, int mask, void
> *devdata,
> + ÂÂÂÂÂÂstruct thermal_zone_device_ops
> *ops,
> + ÂÂÂÂÂÂconst struct
> thermal_zone_params *tzp,
> + ÂÂÂÂÂÂint passive_delay, int
> polling_delay))
> Â
> ÂÂÂÂÂ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
> +ÂÂÂÂ/sys/class/thermal folder as `thermal_zone[0-*]`. It tries to
> bind all the
> ÂÂÂÂÂthermal cooling devices registered at the same time.
> Â
> -ÂÂÂÂtype: the thermal zone type.
> -ÂÂÂÂtrips: the total number of trip points this thermal zone
> supports.
> -ÂÂÂÂmask: Bit string: If 'n'th bit is set, then trip point 'n' is
> writeable.
> -ÂÂÂÂ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.
> - .set_trips: set the trip points window. Whenever the current
> temperature
> +ÂÂÂÂtype:
> + the thermal zone type.
> +ÂÂÂÂtrips:
> + the total number of trip points this thermal zone supports.
> +ÂÂÂÂmask:
> + Bit string: If 'n'th bit is set, then trip point 'n' is
> writeable.
> +ÂÂÂÂ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.
> + .set_trips:
> + ÂÂÂÂset the trip points window. Whenever the current
> temperature
> Â ÂÂÂÂis updated, the trip points immediately below
> and above the
> Â ÂÂÂÂcurrent temperature are found.
> - .get_mode: get the current mode (enabled/disabled) of the
> thermal zone.
> - ÂÂÂÂ- "enabled" means the kernel thermal management is
> enabled.
> - ÂÂÂÂ- "disabled" will prevent kernel thermal driver action
> upon trip points
> - ÂÂÂÂÂÂso that user applications can take charge of thermal
> management.
> - .set_mode: set the mode (enabled/disabled) 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
> + .get_mode:
> + ÂÂÂget the current mode (enabled/disabled) of the
> thermal zone.
> +
> + - "enabled" means the kernel thermal
> management is
> + ÂÂenabled.
> + - "disabled" will prevent kernel thermal
> driver action
> + ÂÂupon trip points so that user applications
> can take
> + ÂÂcharge of thermal management.
> + .set_mode:
> + set the mode (enabled/disabled) 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.
> - .set_emul_temp: set the emulation temperature which helps in
> debugging
> + .set_emul_temp:
> + set the emulation temperature which helps in
> debugging
> Â different threshold temperature points.
> -ÂÂÂÂtzp: thermal zone platform parameters.
> -ÂÂÂÂpassive_delay: number of milliseconds to wait between polls when
> +ÂÂÂÂtzp:
> + thermal zone platform parameters.
> +ÂÂÂÂpassive_delay:
> + number of milliseconds to wait between polls when
> Â performing passive cooling.
> -ÂÂÂÂpolling_delay: number of milliseconds to wait between polls when
> checking
> +ÂÂÂÂpolling_delay:
> + number of milliseconds to wait between polls when checking
> Â whether trip points have been crossed (0 for interrupt
> driven systems).
> Â
> +ÂÂÂÂ::
> Â
> -1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device
> *tz)
> + void thermal_zone_device_unregister(struct
> thermal_zone_device *tz)
> Â
> ÂÂÂÂÂThis interface function removes the thermal zone device.
> ÂÂÂÂÂIt deletes the corresponding entry from /sys/class/thermal
> folder and
> ÂÂÂÂÂunbinds all the thermal cooling devices it uses.
> Â
> -1.1.3 struct thermal_zone_device *thermal_zone_of_sensor_register(
> - struct device *dev, int sensor_id, void *data,
> - const struct thermal_zone_of_device_ops *ops)
> + ::
> +
> + ÂÂÂstruct thermal_zone_device
> + ÂÂÂ*thermal_zone_of_sensor_register(struct device *dev, int
> sensor_id,
> + void *data,
> + const struct
> thermal_zone_of_device_ops *ops)
> Â
> Â This interface adds a new sensor to a DT thermal zone.
> Â This function will search the list of thermal zones
> described in
> @@ -87,25 +120,33 @@ temperature) and throttle appropriate devices.
> Â thermal zone device.
> Â
> Â The parameters for this interface are:
> - dev: Device node of sensor containing valid
> node pointer in
> +
> + dev:
> + Device node of sensor containing valid node
> pointer in
> Â dev->of_node.
> - sensor_id: a sensor identifier, in case the sensor IP
> has more
> + sensor_id:
> + a sensor identifier, in case the sensor IP
> has more
> Â than one sensors
> - data: a private pointer (owned by the caller)
> that will be
> + data:
> + a private pointer (owned by the caller) that
> will be
> Â passed back, when a temperature reading is
> needed.
> - ops: struct thermal_zone_of_device_ops *.
> + ops:
> + `struct thermal_zone_of_device_ops *`.
> Â
> - get_temp: a pointer to a function
> that reads the
> + ==============ÂÂ============================
> ===========
> + get_temp a pointer to a function that
> reads the
> Â sensor temperature. This is
> mandatory
> Â callback provided by sensor
> driver.
> - set_trips:ÂÂÂÂÂÂa pointer to a function that
> sets a
> + set_trips a pointer to a function
> that sets a
> Â temperature window. When
> this window is
> Â left the driver must inform
> the thermal
> Â core via
> thermal_zone_device_update.
> - get_trend:Â a pointer to a function
> that reads the
> + get_trendÂ a pointer to a function
> that reads the
> Â sensor temperature trend.
> - set_emul_temp: a pointer to a
> function that sets
> + set_emul_temp a pointer to a function
> that sets
> Â sensor emulated temperature.
> + ==============ÂÂ============================
> ===========
> +
> Â The thermal zone temperature is provided by the get_temp()
> function
> Â pointer of thermal_zone_of_device_ops. When called, it will
> Â have the private pointer @data back.
> @@ -114,8 +155,10 @@ temperature) and throttle appropriate devices.
> Â handle. Caller should check the return handle with IS_ERR()
> for finding
> Â whether success or not.
> Â
> -1.1.4 void thermal_zone_of_sensor_unregister(struct device *dev,
> - struct thermal_zone_device *tzd)
> + ::
> +
> + ÂÂÂÂvoid thermal_zone_of_sensor_unregister(struct device
> *dev,
> + ÂÂÂstruct
> thermal_zone_device *tzd)
> Â
> Â This interface unregisters a sensor from a DT thermal zone
> which was
> Â successfully added by interface
> thermal_zone_of_sensor_register().
> @@ -124,21 +167,29 @@ temperature) and throttle appropriate devices.
> Â interface. It will also silent the zone by remove the
> .get_temp() and
> Â get_trend() thermal zone device callbacks.
> Â
> -1.1.5 struct thermal_zone_device
> *devm_thermal_zone_of_sensor_register(
> - struct device *dev, int sensor_id,
> - void *data, const struct thermal_zone_of_device_ops
> *ops)
> + ::
> +
> + ÂÂstruct thermal_zone_device
> + ÂÂ*devm_thermal_zone_of_sensor_register(struct device *dev,
> + int sensor_id,
> + void *data,
> + const struct
> thermal_zone_of_device_ops *ops)
> Â
> Â This interface is resource managed version of
> Â thermal_zone_of_sensor_register().
> +
> Â All details of thermal_zone_of_sensor_register() described
> in
> Â section 1.1.3 is applicable here.
> +
> Â The benefit of using this interface to register sensor is
> that it
> Â is not require to explicitly call
> thermal_zone_of_sensor_unregister()
> Â in error path or during driver unbinding as this is done by
> driver
> Â resource manager.
> Â
> -1.1.6 void devm_thermal_zone_of_sensor_unregister(struct device
> *dev,
> - struct thermal_zone_device *tzd)
> + ::
> +
> + void devm_thermal_zone_of_sensor_unregister(struct
> device *dev,
> + struct
> thermal_zone_device *tzd)
> Â
> Â This interface is resource managed version of
> Â thermal_zone_of_sensor_unregister().
> @@ -147,123 +198,186 @@ temperature) and throttle appropriate
> devices.
> Â Normally this function will not need to be called and the
> resource
> Â management code will ensure that the resource is freed.
> Â
> -1.1.7 int thermal_zone_get_slope(struct thermal_zone_device *tz)
> + ::
> +
> + int thermal_zone_get_slope(struct
> thermal_zone_device *tz)
> Â
> Â This interface is used to read the slope attribute value
> Â for the thermal zone device, which might be useful for
> platform
> Â drivers for temperature calculations.
> Â
> -1.1.8 int thermal_zone_get_offset(struct thermal_zone_device *tz)
> + ::
> +
> + int thermal_zone_get_offset(struct
> thermal_zone_device *tz)
> Â
> Â This interface is used to read the offset attribute value
> Â for the thermal zone device, which might be useful for
> platform
> Â drivers for temperature calculations.
> Â
> Â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 *)
> +------------------------------------
> +
> +
> +ÂÂÂÂ::
> +
> + 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 /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries
> to bind itself
> ÂÂÂÂÂto all the thermal zone devices registered 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 Currently requested 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)
> +
> +ÂÂÂÂ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 Currently requested throttle state of the
> + cooling device.
> + .set_cur_state:
> + set the Current throttle state of the cooling
> device.
> +
> +ÂÂÂÂ::
> +
> + void thermal_cooling_device_unregister(struct
> thermal_cooling_device *cdev)
> Â
> ÂÂÂÂÂThis interface function removes the thermal cooling device.
> ÂÂÂÂÂIt deletes the corresponding entry from /sys/class/thermal
> folder and
> ÂÂÂÂÂunbinds 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,
> - unsigned long upper, unsigned long lower, unsigned int
> weight);
> +------------------------------------------------------------------
> -----------
> +
> +ÂÂÂÂ::
> +
> + int thermal_zone_bind_cooling_device(struct
> thermal_zone_device *tz,
> + int trip, struct thermal_cooling_device *cdev,
> + unsigned long upper, unsigned long lower, unsigned
> int weight);
> Â
> ÂÂÂÂÂThis interface function binds a thermal cooling device to a
> particular 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 in this thermal zone the
> cooling device
> -ÂÂÂÂÂÂÂÂÂÂis associated with.
> -ÂÂÂÂupper:the Maximum cooling state for this trip point.
> -ÂÂÂÂÂÂÂÂÂÂTHERMAL_NO_LIMIT means no upper limit,
> +
> +ÂÂÂÂtz:
> + ÂÂthe thermal zone device
> +ÂÂÂÂcdev:
> + ÂÂthermal cooling device
> +ÂÂÂÂtrip:
> + ÂÂindicates which trip point in this thermal zone the
> cooling device
> + ÂÂis associated with.
> +ÂÂÂÂupper:
> + ÂÂthe Maximum cooling state for this trip point.
> + ÂÂTHERMAL_NO_LIMIT means no upper limit,
> Â ÂÂand the cooling device can be in max_state.
> -ÂÂÂÂlower:the Minimum cooling state can be used for this trip point.
> -ÂÂÂÂÂÂÂÂÂÂTHERMAL_NO_LIMIT means no lower limit,
> +ÂÂÂÂlower:
> + ÂÂthe Minimum cooling state can be used for this trip point.
> + ÂÂTHERMAL_NO_LIMIT means no lower limit,
> Â ÂÂand the cooling device can be in cooling state 0.
> -ÂÂÂÂweight: the influence of this cooling device in this thermal
> -ÂÂÂÂÂÂÂÂÂÂÂÂzone.ÂÂSee 1.4.1 below for more information.
> +ÂÂÂÂweight:
> + ÂÂthe influence of this cooling device in this thermal
> + ÂÂzone.ÂÂSee 1.4.1 below for more information.
> Â
> -1.3.2 int thermal_zone_unbind_cooling_device(struct
> thermal_zone_device *tz,
> - int trip, struct thermal_cooling_device *cdev);
> +ÂÂÂÂ::
> +
> + int thermal_zone_unbind_cooling_device(struct
> thermal_zone_device *tz,
> + int trip, struct
> thermal_cooling_device *cdev);
> Â
> ÂÂÂÂÂThis interface function unbinds a thermal cooling device from a
> particular
> ÂÂÂÂÂ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 in this thermal zone the
> cooling device
> -ÂÂÂÂÂÂÂÂÂÂis associated with.
> +
> +ÂÂÂÂtz:
> + the thermal zone device
> +ÂÂÂÂcdev:
> + thermal cooling device
> +ÂÂÂÂtrip:
> + indicates which trip point in this thermal zone the cooling
> device
> + is associated with.
> Â
> Â1.4 Thermal Zone Parameters
> -1.4.1 struct thermal_bind_params
> +---------------------------
> +
> +ÂÂÂÂ::
> +
> + struct thermal_bind_params
> +
> ÂÂÂÂÂThis structure defines the following parameters that are used to
> bind
> ÂÂÂÂÂa zone with a cooling device for a particular trip point.
> -ÂÂÂÂ.cdev: The cooling device pointer
> -ÂÂÂÂ.weight: The 'influence' of a particular cooling device on this
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂzone. This is relative to the rest of the cooling
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂdevices. For example, if all cooling devices have a
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂweight of 1, then they all contribute the same. You can
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂuse percentages if you want, but it's not mandatory. A
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂweight of 0 means that this cooling device doesn't
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂcontribute to the cooling of this zone unless all
> cooling
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂdevices have a weight of 0. If all weights are 0, then
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂthey all contribute the same.
> -ÂÂÂÂ.trip_mask:This is a bit mask that gives the binding relation
> between
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂthis thermal zone and cdev, for a particular trip
> point.
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂIf nth bit is set, then the cdev and thermal zone are
> bound
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂfor trip point n.
> -ÂÂÂÂ.binding_limits: This is an array of cooling state limits. Must
> have
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂexactly 2 * thermal_zone.number_of_trip_points.
> It is an
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂarray consisting of tuples <lower-state upper-
> state> of
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂstate limits. Each trip will be associated with
> one state
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂlimit tuple when binding. A NULL pointer means
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ<THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all
> trips.
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂThese limits are used when binding a cdev to a
> trip point.
> -ÂÂÂÂ.match: This call back returns success(0) if the 'tz and cdev'
> need to
> +
> +ÂÂÂÂ.cdev:
> + ÂÂÂÂÂThe cooling device pointer
> +ÂÂÂÂ.weight:
> + ÂÂÂÂÂThe 'influence' of a particular cooling device on this
> + ÂÂÂÂÂzone. This is relative to the rest of the cooling
> + ÂÂÂÂÂdevices. For example, if all cooling devices have a
> + ÂÂÂÂÂweight of 1, then they all contribute the same. You can
> + ÂÂÂÂÂuse percentages if you want, but it's not mandatory. A
> + ÂÂÂÂÂweight of 0 means that this cooling device doesn't
> + ÂÂÂÂÂcontribute to the cooling of this zone unless all
> cooling
> + ÂÂÂÂÂdevices have a weight of 0. If all weights are 0, then
> + ÂÂÂÂÂthey all contribute the same.
> +ÂÂÂÂ.trip_mask:
> + ÂÂÂÂÂÂÂThis is a bit mask that gives the binding relation
> between
> + ÂÂÂÂÂÂÂthis thermal zone and cdev, for a particular trip
> point.
> + ÂÂÂÂÂÂÂIf nth bit is set, then the cdev and thermal zone are
> bound
> + ÂÂÂÂÂÂÂfor trip point n.
> +ÂÂÂÂ.binding_limits:
> + ÂÂÂÂÂThis is an array of cooling state limits. Must
> have
> + ÂÂÂÂÂexactly 2 * thermal_zone.number_of_trip_points.
> It is an
> + ÂÂÂÂÂarray consisting of tuples <lower-state upper-
> state> of
> + ÂÂÂÂÂstate limits. Each trip will be associated with
> one state
> + ÂÂÂÂÂlimit tuple when binding. A NULL pointer means
> + ÂÂÂÂÂ<THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all
> trips.
> + ÂÂÂÂÂThese limits are used when binding a cdev to a
> trip point.
> +ÂÂÂÂ.match:
> + ÂÂÂÂThis call back returns success(0) if the 'tz and cdev'
> need to
> Â ÂÂÂÂbe bound, as per platform data.
> -1.4.2 struct thermal_zone_params
> +
> +ÂÂÂÂ::
> +
> + struct thermal_zone_params
> +
> ÂÂÂÂÂThis structure defines the platform level parameters for a
> thermal zone.
> ÂÂÂÂÂThis data, for each thermal zone should come from the platform
> layer.
> ÂÂÂÂÂThis is an optional feature where some platforms can choose not
> to
> ÂÂÂÂÂprovide this data.
> -ÂÂÂÂ.governor_name: Name of the thermal governor used for this zone
> -ÂÂÂÂ.no_hwmon: a boolean to indicate if the thermal to hwmon sysfs
> interface
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂis required. when no_hwmon == false, a hwmon sysfs
> interface
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂwill be created. when no_hwmon == true, nothing will
> be done.
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂIn case the thermal_zone_params is NULL, the hwmon
> interface
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂwill be created (for backward compatibility).
> -ÂÂÂÂ.num_tbps: Number of thermal_bind_params entries for this zone
> -ÂÂÂÂ.tbp: thermal_bind_params entries
> +
> +ÂÂÂÂ.governor_name:
> + ÂÂÂÂÂÂÂName of the thermal governor used for this zone
> +ÂÂÂÂ.no_hwmon:
> + ÂÂÂÂÂÂÂa boolean to indicate if the thermal to hwmon sysfs
> interface
> + ÂÂÂÂÂÂÂis required. when no_hwmon == false, a hwmon sysfs
> interface
> + ÂÂÂÂÂÂÂwill be created. when no_hwmon == true, nothing will
> be done.
> + ÂÂÂÂÂÂÂIn case the thermal_zone_params is NULL, the hwmon
> interface
> + ÂÂÂÂÂÂÂwill be created (for backward compatibility).
> +ÂÂÂÂ.num_tbps:
> + ÂÂÂÂÂÂÂNumber of thermal_bind_params entries for this zone
> +ÂÂÂÂ.tbp:
> + ÂÂÂÂÂÂÂthermal_bind_params entries
> Â
> Â2. sysfs attributes structure
> +=============================
> Â
> +== ================
> ÂRO read only value
> ÂWO write 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-*]:
> +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
> @@ -282,8 +396,9 @@ Thermal zone device sys I/F, created once it's
> registered:
> ÂÂÂÂÂ|---slope:ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂSlope constant applied as linear
> extrapolation
> ÂÂÂÂÂ|---offset:ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂOffset constant applied as linear
> extrapolation
> Â
> -Thermal cooling device sys I/F, created once it's registered:
> -/sys/class/thermal/cooling_device[0-*]:
> +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
> @@ -299,11 +414,13 @@ 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-*]:
> +::
> +
> +ÂÂ/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
> ÂÂÂÂÂ|---cdev[0-*]_weight:ÂÂÂÂÂÂÂInfluence of the cooling device in
> -ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂthis thermal zone
> + this thermal zone
> Â
> Â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_
> @@ -311,16 +428,17 @@ 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-*]:
> +::
> +
> +ÂÂ/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.rst for additional
> information.
> Â
> -***************************
> -* Thermal zone attributes *
> -***************************
> +Thermal zone attributes
> +-----------------------
> Â
> Âtype
> Â Strings which represent the thermal zone type.
> @@ -340,54 +458,67 @@ mode
> Â 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
> +
> + 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
> +`trip_point_[0-*]_temp`
> Â The temperature above which trip point will be fired.
> +
> Â Unit: millidegree Celsius
> +
> Â RO, Optional
> Â
> -trip_point_[0-*]_type
> +`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
> +
> + E.g. it can be one of critical, hot, passive, `active[0-*]`
> for ACPI
> Â thermal zone.
> +
> Â RO, Optional
> Â
> -trip_point_[0-*]_hyst
> +`trip_point_[0-*]_hyst`
> Â The hysteresis value for a trip point, represented as an
> integer
> Â Unit: Celsius
> Â RW, Optional
> Â
> -cdev[0-*]
> +`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
> +`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
> +`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
> Â
> Âpassive
> Â Attribute is only present for zones in which the passive
> cooling
> @@ -395,8 +526,11 @@ passive
> Â and can be set to a temperature (in millidegrees) to enable
> a
> Â passive trip point for the zone. Activation is done by
> polling with
> Â an interval of 1 second.
> +
> Â Unit: millidegrees Celsius
> +
> Â Valid values: 0 (disabled) or greater than 1000
> +
> Â RW, Optional
> Â
> Âemul_temp
> @@ -407,17 +541,21 @@ emul_temp
> Â 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.
> + ÂÂ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/thermal/power_allocator.txt
> + more information see
> Documentation/thermal/power_allocator.rst
> +
> Â Unit: milliwatts
> +
> Â RW, Optional
> Â
> Âk_po
> @@ -425,7 +563,8 @@ k_po
> Â controller during temperature overshoot. Temperature
> overshoot
> Â is when the current temperature is above the "desired
> Â temperature" trip point. For more information see
> - Documentation/thermal/power_allocator.txt
> + Documentation/thermal/power_allocator.rst
> +
> Â RW, Optional
> Â
> Âk_pu
> @@ -433,20 +572,23 @@ k_pu
> Â controller during temperature undershoot. Temperature
> undershoot
> Â is when the current temperature is below the "desired
> Â temperature" trip point. For more information see
> - Documentation/thermal/power_allocator.txt
> + Documentation/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/thermal/power_allocator.txt
> + Documentation/thermal/power_allocator.rst
> +
> Â RW, Optional
> Â
> Âk_d
> Â The derivative term of the power allocator governor's PID
> Â controller. For more information see
> - Documentation/thermal/power_allocator.txt
> + Documentation/thermal/power_allocator.rst
> +
> Â RW, Optional
> Â
> Âintegral_cutoff
> @@ -456,8 +598,10 @@ integral_cutoff
> Â 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/thermal/power_allocator.txt
> + Documentation/thermal/power_allocator.rst
> +
> Â Unit: millidegree Celsius
> +
> Â RW, Optional
> Â
> Âslope
> @@ -465,6 +609,7 @@ slope
> Â 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
> @@ -472,28 +617,33 @@ offset
> Â 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 *
> -*****************************
> +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
> @@ -508,9 +658,11 @@ stats/time_in_state_ms:
> Â units here is 10mS (similar to other time exported in
> /proc).
> Â 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:
> @@ -522,6 +674,7 @@ stats/trans_table:
> Â RO, 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,
> @@ -532,11 +685,10 @@ thermal_cooling_device. Both are considered to
> have the same
> Âeffectiveness in cooling the thermal zone.
> Â
> Â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:
> +method, the sys I/F structure will be built like this::
> Â
> -/sys/class/thermal:
> -
> -|thermal_zone1:
> + /sys/class/thermal:
> +ÂÂ|thermal_zone1:
> ÂÂÂÂÂ|---type: acpitz
> ÂÂÂÂÂ|---temp: 37000
> ÂÂÂÂÂ|---mode: enabled
> @@ -557,24 +709,24 @@ method, the sys I/F structure will be built
> like this:
> ÂÂÂÂÂ|---cdev1_trip_point: 2 /* cdev1 can be used for
> active[0]*/
> ÂÂÂÂÂ|---cdev1_weight:ÂÂÂÂÂÂÂÂÂÂÂ1024
> Â
> -|cooling_device0:
> +ÂÂ|cooling_device0:
> ÂÂÂÂÂ|---type: Processor
> ÂÂÂÂÂ|---max_state: 8
> ÂÂÂÂÂ|---cur_state: 0
> Â
> -|cooling_device3:
> +ÂÂ|cooling_device3:
> ÂÂÂÂÂ|---type: Fan
> ÂÂÂÂÂ|---max_state: 2
> ÂÂÂÂÂ|---cur_state: 0
> Â
> -/sys/class/hwmon:
> -
> -|hwmon0:
> + /sys/class/hwmon:
> +ÂÂ|hwmon0:
> ÂÂÂÂÂ|---name: acpitz
> ÂÂÂÂÂ|---temp1_input: 37000
> ÂÂÂÂÂ|---temp1_crit: 100000
> Â
> Â4. Event Notification
> +=====================
> Â
> ÂThe framework includes a simple notification mechanism, in the form
> of a
> Ânetlink event. Netlink socket initialization is done during the
> _init_
> @@ -587,21 +739,28 @@ event will be one of:{THERMAL_AUX0,
> THERMAL_AUX1, THERMAL_CRITICAL,
> ÂTHERMAL_DEV_FAULT}. Notification can be sent when the current
> temperature
> Âcrosses any of the configured thresholds.
> Â
> -5. Export Symbol APIs:
> +5. Export Symbol APIs
> +=====================
> +
> +5.1. get_tz_trend
> +-----------------
> Â
> -5.1: get_tz_trend:
> ÂThis function returns the trend of a thermal zone, i.e the rate of
> change
> Âof temperature of the thermal zone. Ideally, the thermal sensor
> drivers
> Âare supposed to implement the callback. If they don't, the thermal
> Âframework calculated the trend by comparing the previous and the
> current
> Âtemperature values.
> Â
> -5.2:get_thermal_instance:
> +5.2. get_thermal_instance
> +-------------------------
> +
> ÂThis function returns the thermal_instance corresponding to a given
> Â{thermal_zone, cooling_device, trip_point} combination. Returns NULL
> Âif such an instance does not exist.
> Â
> -5.3:thermal_notify_framework:
> +5.3. thermal_notify_framework
> +-----------------------------
> +
> ÂThis function handles the trip events from sensor drivers. It starts
> Âthrottling the cooling devices according to the policy configured.
> ÂFor CRITICAL and HOT trip points, this notifies the respective
> drivers,
> @@ -609,12 +768,15 @@ and does actual throttling for other trip
> points i.e ACTIVE and PASSIVE.
> ÂThe throttling policy is based on the configured platform data; if
> no
> Âplatform data is provided, this uses the step_wise throttling
> policy.
> Â
> -5.4:thermal_cdev_update:
> +5.4. thermal_cdev_update
> +------------------------
> +
> ÂThis function serves as an arbitrator to set the state of a cooling
> Âdevice. It sets the cooling device to the deepest cooling state if
> Âpossible.
> Â
> -6. thermal_emergency_poweroff:
> +6. thermal_emergency_poweroff
> +=============================
> Â
> ÂOn an event of critical trip temperature crossing. Thermal framework
> Âallows the system to shutdown gracefully by calling
> orderly_poweroff().
> diff --git a/Documentation/thermal/x86_pkg_temperature_thermal
> b/Documentation/thermal/x86_pkg_temperature_thermal.rst
> similarity index 80%
> rename from Documentation/thermal/x86_pkg_temperature_thermal
> rename to Documentation/thermal/x86_pkg_temperature_thermal.rst
> index 17a3a4c0a0ca..f134dbd3f5a9 100644
> --- a/Documentation/thermal/x86_pkg_temperature_thermal
> +++ b/Documentation/thermal/x86_pkg_temperature_thermal.rst
> @@ -1,19 +1,23 @@
> +===================================
> ÂKernel driver: x86_pkg_temp_thermal
> -===================
> +===================================
> Â
> ÂSupported chips:
> +
> Â* x86: with package level thermal management
> +
> Â(Verify using: CPUID.06H:EAX[bit 6] =1)
> Â
> ÂAuthors: Srinivas Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx>
> Â
> ÂReference
> ----
> +---------
> +
> ÂIntelÂ 64 and IA-32 Architectures Software Developerâs Manual (Jan,
> 2013):
> ÂChapter 14.6: PACKAGE LEVEL THERMAL MANAGEMENT
> Â
> ÂDescription
> ----------
> +-----------
> Â
> ÂThis driver register CPU digital temperature package level sensor as
> a thermal
> Âzone with maximum two user mode configurable trip points. Number of
> trip points
> @@ -25,23 +29,27 @@ take any action to control temperature.
> ÂThreshold management
> Â--------------------
> ÂEach package will register as a thermal zone under
> /sys/class/thermal.
> -Example:
> -/sys/class/thermal/thermal_zone1
> +
> +Example::
> +
> + /sys/class/thermal/thermal_zone1
> Â
> ÂThis contains two trip points:
> +
> Â- trip_point_0_temp
> Â- trip_point_1_temp
> Â
> ÂUser can set any temperature between 0 to TJ-Max temperature.
> Temperature units
> -are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-
> api.txt" for
> +are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-
> api.rst" for
> Âthermal sys-fs details.
> Â
> ÂAny value other than 0 in these trip points, can trigger thermal
> notifications.
> ÂSetting 0, stops sending thermal notifications.
> Â
> -Thermal notifications: To get kobject-uevent notifications, set the
> thermal zone
> -policy to "user_space". For example: echo -n "user_space" > policy
> -
> -
> +Thermal notifications:
> +To get kobject-uevent notifications, set the thermal zone
> +policy to "user_space".
> Â
> +For example::
> Â
> + echo -n "user_space" > policy
> diff --git a/MAINTAINERS b/MAINTAINERS
> index d9e214f68e52..b2254bc8e495 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -15687,7 +15687,7 @@ M: Viresh Kumar <viresh.kumar@xxxxxxxx
> rg>
> ÂM: Javi Merino <javi.merino@xxxxxxxxxx>
> ÂL: linux-pm@xxxxxxxxxxxxxxx
> ÂS: Supported
> -F: Documentation/thermal/cpu-cooling-api.txt
> +F: Documentation/thermal/cpu-cooling-api.rst
> ÂF: drivers/thermal/cpu_cooling.c
> ÂF: include/linux/cpu_cooling.h
> Â
> diff --git a/include/linux/thermal.h b/include/linux/thermal.h
> index 15a4ca5d7099..681047f8cc05 100644
> --- a/include/linux/thermal.h
> +++ b/include/linux/thermal.h
> @@ -251,7 +251,7 @@ struct thermal_bind_params {
> Â Â* platform characterization. This value is relative to the
> Â Â* rest of the weights so a cooling device whose weight is
> Â Â* double that of another cooling device is twice as
> - Â* effective. See Documentation/thermal/sysfs-api.txt for
> more
> + Â* effective. See Documentation/thermal/sysfs-api.rst for
> more
> Â Â* information.
> Â Â*/
> Â int weight;
> @@ -259,7 +259,7 @@ struct thermal_bind_params {
> Â /*
> Â Â* This is a bit mask that gives the binding relation
> between this
> Â Â* thermal zone and cdev, for a particular trip point.
> - Â* See Documentation/thermal/sysfs-api.txt for more
> information.
> + Â* See Documentation/thermal/sysfs-api.rst for more
> information.
> Â Â*/
> Â int trip_mask;
> Â

Next message: Thierry Reding: "Re: [PATCH V4 03/18] gpio: tegra: use resume_noirq for tegra gpio resume"
Previous message: Will Deacon: "Re: [PATCH v3 3/4] iommu/arm-smmu: Add support to handle Qcom's wait-for-safe logic"
Next in thread: Mauro Carvalho Chehab: "Re: [PATCH v1 04/22] docs: thermal: convert to ReST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]