docs: thermal: convert to ReST

=======================

CPU cooling APIs How To

===================================

=======================

Written by Amit Daniel Kachhap <amit.kachhap@linaro.org>

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

  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

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

========================

Kernel driver exynos_tmu

=================

========================

Supported chips:

* ARM SAMSUNG EXYNOS4, EXYNOS5 series of SoC

  Datasheet: Not publicly available

Authors: Donggeun Kim <dg77.kim@samsung.com>

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

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

  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.

EXYNOS EMULATION MODE

========================

=====================

Exynos Emulation Mode

=====================

Copyright (C) 2012 Samsung Electronics

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 |

	    |

: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

=======================

			 INTEL POWERCLAMP DRIVER

Intel Powerclamp Driver

=======================

By: Arjan van de Ven <arjan@linux.intel.com>

    Jacob Pan <jacob.jun.pan@linux.intel.com>

Contents:

By:

  - Arjan van de Ven <arjan@linux.intel.com>

  - Jacob Pan <jacob.jun.pan@linux.intel.com>

.. Contents:

	(*) Introduction

	    - Goals and Objectives

	    - Generic Thermal Layer (sysfs)

	    - Kernel APIs (TBD)

============

INTRODUCTION

============

shown over taking the CPU offline or modulating the CPU clock.

===================

THEORY OF OPERATION

===================

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:

These MSRs are::

      #define MSR_PKG_C2_RESIDENCY      0x60D

      #define MSR_PKG_C3_RESIDENCY      0x3F8

      #define MSR_PKG_C6_RESIDENCY      0x3F9

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     |

	slowing down CPU activities.

A debugfs file is provided for the user to examine compensation

progress and results, such as on a Westmere system.

progress and results, such as on a Westmere system::

  [jacob@nex01 ~]$ cat

  /sys/kernel/debug/intel_powerclamp/powerclamp_calib

  controlling cpu: 0

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).

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

100% busy state with the disabled state.

Example usage:

- To inject 25% idle time

- 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

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