[PATCH RFC 00/12] The Linux Kernel Thermal Framework Docbook

[PATCH RFC 00/12] The Linux Kernel Thermal Framework Docbook

[Eduardo Valentin]

(sorry if you got this duplicated, this time I am copying the mailing lists)

Hello Rui, linux-pm,

It's been some time that I have started this documentation project. The target
is to organize the thermal code documentation, using the kernel docbook format.
In other words, the Linux kernel Documentation would be earning a new Docbook,
a thermal Docbook.

The work is in progress. I started a few chapters, but never got the chance to finish
what I initially intended. However, I decided to share already with you because
I would like to hear what people would like to see in the Docbook.

The whole idea is to consolidate what we have currently spread under Documentation,
in a single place, the new Docbook. So, we would be moving the Documentation/thermal/sysfs-api.txt
content to this Docbook (not done yet).

The overall content organization that I am envisioning is organized in the following Chapters:
1 - Introduction: Overall thermal problem statement and the Linux Kernel solution. In here we should also
give an overview of the framework design strategies and decisions. Under sysfs-api.txt we have something
talking about it, but I believe it got dated already. In this chapter, we also include a small dictionary.
Current status: In progress
2 - Governors: In here we would document all the existing governors and their implemented policies. Also,
I would like to have a simple example on how to write your own thermal governor.
Current status: In progress.
3 - Cooling Devices: I believe here we should include the documentation of the existing cooling devices in
the kernel tree. Also, we should include an example on how to implement a cooling device.
4 - Thermal zone drivers: An example on a simple thermal zone device driver code. Discussion on the multiple
ways of implementing one: standard, of-thermal support, etc.
5 - Generic code: Documentation of the design decision of our generic drivers: cpu cooling, clock cooling,
of-thermal, etc.
6 - User space ABI: Documentation of what we expose to userland.
7 - API Reference: A chapter with the documentation coming from in code comments.

The current code needs a couple of fixes to achieve Chapter 6, API Reference, though. I am
sending in this series a couple of examples of what needs to be fixed.

The content of Chapter 6 and Chapter 7 is more or less an overlap of what we have mostly
inside sysfs-api.txt. I believe it is easier to maintain code comments than maintaining a
separate file to talk about code documentation. Therefore the motivation to write the Docbook.
Besides, within this Docbook we should cover a better overview of the framework, that we currently lack.

I am not sure if we need to have specific thermal zone driver documentation. Probably not. But driver
authors, rise your voice if you would like to have one.

Comments are welcome.

BR,

Eduardo Valentin (12):
  Documentation: Introduce Linux Kernel Thermal Framework DocBook
  Documentation: thermal docbook: add glossary
  thermal: cpu_cooling: remove duplicate documentation entries
  thermal: of-thermal: remove kernel doc warn
  thermal: thermal.h: minor kernel doc fix
  thermal: thermal_core: correct kernel doc wording on
    thermal_zone_get_temp
  Documentation: thermal docbook: introduce API reference chapter
  thermal: fair share: fix kernel doc entry
  thermal: user space: fix kernel doc entry
  thermal: bang bang: fix kernel doc entry
  thermal: step wise: fix kernel doc entry
  Documentation: thermal docbook: introduce governor chapter

 Documentation/DocBook/Makefile     |   3 +-
 Documentation/DocBook/thermal.tmpl | 291 +++++++++++++++++++++++++++++++++++++
 drivers/thermal/fair_share.c       |   5 +-
 drivers/thermal/gov_bang_bang.c    |   5 +-
 drivers/thermal/of-thermal.c       |   2 +-
 drivers/thermal/step_wise.c        |  25 +++-
 drivers/thermal/thermal_core.c     |   2 +-
 drivers/thermal/user_space.c       |   5 +-
 include/linux/cpu_cooling.h        |  13 --
 include/linux/thermal.h            |   2 +-
 10 files changed, 326 insertions(+), 27 deletions(-)
 create mode 100644 Documentation/DocBook/thermal.tmpl

-- 
2.1.3

[PATCH RFC 01/12] Documentation: Introduce Linux Kernel Thermal Framework DocBook

[Eduardo Valentin]

This patch adds a book about the Linux Kernel Thermal Framework.
In this change, only a brief introduction is added together with
Makefile changes.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 Documentation/DocBook/Makefile     |  3 +-
 Documentation/DocBook/thermal.tmpl | 88 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/DocBook/thermal.tmpl

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 9c7d92d..8163508 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -15,7 +15,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
 	    80211.xml debugobjects.xml sh.xml regulator.xml \
 	    alsa-driver-api.xml writing-an-alsa-driver.xml \
 	    tracepoint.xml drm.xml media_api.xml w1.xml \
-	    writing_musb_glue_layer.xml crypto-API.xml
+	    writing_musb_glue_layer.xml crypto-API.xml thermal.xml
+	    writing_musb_glue_layer.xml
 
 include Documentation/DocBook/media/Makefile
 
diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
new file mode 100644
index 0000000..f8fb8a2
--- /dev/null
+++ b/Documentation/DocBook/thermal.tmpl
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
+
+<book id="thermal-api">
+ <bookinfo>
+  <title>Linux Kernel Thermal Framework API</title>
+
+  <authorgroup>
+   <author>
+    <firstname>Eduardo</firstname>
+    <surname>Valentin</surname>
+    <affiliation>
+     <address>
+      <email>evalenti@kernel.org</email>
+     </address>
+    </affiliation>
+   </author>
+  </authorgroup>
+
+  <copyright>
+   <year>2008-2014</year>
+   <holder>Eduardo Valentin</holder>
+   <holder>Sujith Thomas</holder>
+   <holder>Zhang Rui</holder>
+  </copyright>
+  <legalnotice>
+   <para>
+     This documentation is free software; you can redistribute
+     it and/or modify it under the terms of the GNU General Public
+     License version 2 as published by the Free Software Foundation.
+   </para>
+
+   <para>
+     This program is distributed in the hope that it will be
+     useful, but WITHOUT ANY WARRANTY; without even the implied
+     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+     See the GNU General Public License for more details.
+   </para>
+
+   <para>
+     For more details see the file COPYING in the source
+     distribution of Linux.
+   </para>
+  </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+
+	<chapter id="introduction">
+		<title>Introduction</title>
+		<para>Thermal management is any method or technique implied to
+		mitigate emergencies caused by operating devices within
+		unsupported temperatures. The challenge consists of designing a
+		product keeping the junction temperature of the IC components.
+		The operating temperature of IC components used on products must
+		operate within their design limits. Besides, temperature towards
+		device enclosure must be in a comfort level for the user.
+		Therefore, thermal management, by the time of this writing,
+		starts in very early device design phase. Managing thermal may
+		involve different disciplines, at different stages, such as
+		temperature monitoring, floorplanning, microarchitectural
+		techniques, compiler techniques, OS techniques, liquid cooling,
+		and thermal reliability or security. This document covers what
+		the Linux Kernel Thermal Framework provides as abstraction to
+		users with respect to thermal management.  
+		</para>
+		<para>One of the first proposals to provide a solution to cover
+		the thermal problem appears in the Advanced Configuration and
+		Power Interface (ACPI) specification. ACPI provides an open
+		standard for device configuration and power management by the
+		operating system. However, several computing devices which may
+		have thermal issues in the market disregard the ACPI standard.
+		Therefore, the Linux Kernel Thermal Framework has been designed
+		to serve as abstraction for ACPI and non-ACPI systems. The core
+		concepts applies in both types of systems. 
+		</para>
+		<para>The Linux Kernel Thermal Framework has a design which
+		represents the different thermal constraints found in an
+		end-products. The thermal constraints exist to serve different
+		purposes. There two major types of thermal constraints. The
+		first is related to components junction temperature. The second
+		is related to the level of comfort while end users are handling
+		devices.
+		</para>
+
+  </chapter>
+</book>
-- 
2.1.3

[PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Eduardo Valentin]

This change introduces a section in the Introduction Chapter to
list concepts used by the Thermal Framework.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)

diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
index f8fb8a2..66efed3 100644
--- a/Documentation/DocBook/thermal.tmpl
+++ b/Documentation/DocBook/thermal.tmpl
@@ -84,5 +84,132 @@
 		devices.
 		</para>
 
-  </chapter>
+		<sect1 id="glossary">
+			<title>Glossary</title>
+			<para>The Linux Kernel Thermal Framework  uses a
+			specific terminology to represent the entities involved
+			in thermal constrained environments. This section
+			summaries the terminology as dictionary. These terms are
+			in use within the present document and in the source
+			code of the Linux Kernel Thermal Framework.
+			</para>
+			<glossary>
+				<glossentry>
+					<glossterm>Thermal Zone</glossterm>
+					<glossdef>
+						<para>Thermal zones represent
+						what is the current status of a
+						thermal constrained zone in the
+						hardware. The zone usually is a
+						device or component. The status
+						of a thermal zone is mainly with
+						respect to temperature.
+						Currently, the Linux Kernel
+						Thermal Framework represents
+						temperature in miliCelsius. The
+						current abstraction covers for
+						non negative temperatures and
+						constraints.
+						</para>
+					</glossdef>
+				</glossentry>
+				<glossentry>
+					<glossterm>Thermal Sensors</glossterm>
+					<glossdef>
+						<para>Thermal sensors provide
+						temperature sensing capabilities
+						on thermal zones. Typical
+						devices are I2C ADC converters
+						and bandgaps. These are nodes
+						providing temperature data to
+						thermal zones. Thermal sensor
+						devices may control one or more
+						internal sensors.
+						</para>
+					</glossdef>
+				</glossentry>
+				<glossentry>
+					<glossterm>Trips Points</glossterm>
+					<glossdef>
+						<para>The trip node describes a
+						point in the temperature domain
+						in which the system takes an
+						action. This item describes just
+						the point, not the action. Trip
+						points are represented as
+						temperature in miliCelsius. The
+						current abstraction covers for
+						non negative temperatures.
+						</para>
+					</glossdef>
+				</glossentry>
+				<glossentry>
+					<glossterm>Thermal Governor</glossterm>
+					<glossdef>
+						<para>Thermal Governors
+						represent a policy to manage the
+						thermal zone device temperature.
+						The governor targets to keep
+						temperature in an acceptable
+						range which correlates to the
+						power budget, while maximizing
+						the performance. Governors can
+						be implemented in Kernel Space
+						or in User Space.
+						</para>
+					</glossdef>
+				</glossentry>
+				<glossentry>
+					<glossterm>Thermal Cooling Device</glossterm>
+					<glossdef>
+						<para>Cooling devices provide
+						control on power dissipation.
+						There are essentially two ways
+						to provide control on power
+						dissipation. First is by means
+						of regulating device
+						performance, which is known as
+						passive cooling. A typical
+						passive cooling is a CPU that
+						has dynamic voltage and
+						frequency scaling (DVFS), and
+						uses lower frequencies as
+						cooling states. Second is by
+						means of activating devices in
+						order to remove the dissipated
+						heat, which is known as active
+						cooling, e.g. regulating fan
+						speeds. In both cases, cooling
+						devices shall have a way to
+						determine the state of cooling
+						in which the device is.
+				</para>
+					</glossdef>
+				</glossentry>
+				<glossentry>
+					<glossterm>Cooling State</glossterm>
+					<glossdef>
+						<para>Any cooling device has a
+						range of cooling states (i.e.
+						different levels of heat
+						dissipation). For example a
+						fan's cooling states correspond
+						to the different fan speeds
+						possible. Cooling states are
+						referred to by single unsigned
+						integers, where larger numbers
+						mean greater heat dissipation.
+						The precise set of cooling
+						states associated with a device
+						(as referred to be the
+						cooling-min-state and
+						cooling-max-state properties)
+						should be defined in a
+						particular device's binding.
+						</para>
+					</glossdef>
+				</glossentry>
+			</glossary>
+		</sect1>
+	</chapter>
 </book>
-- 
2.1.3

[PATCH RFC 03/12] thermal: cpu_cooling: remove duplicate documentation entries

[Eduardo Valentin]

This patch removes the kernel docs from cpu_cooling.h.
The entries found in this file are already documented
in cpu_cooling.c. The entries in cpu_cooling.c are more
complete than those in cpu_cooling.h. Thus, removing
from cpu_cooling.h

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 include/linux/cpu_cooling.h | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/include/linux/cpu_cooling.h b/include/linux/cpu_cooling.h
index bd95527..a8d827c 100644
--- a/include/linux/cpu_cooling.h
+++ b/include/linux/cpu_cooling.h
@@ -29,18 +29,9 @@
 #include <linux/cpumask.h>
 
 #ifdef CONFIG_CPU_THERMAL
-/**
- * cpufreq_cooling_register - function to create cpufreq cooling device.
- * @clip_cpus: cpumask of cpus where the frequency constraints will happen
- */
 struct thermal_cooling_device *
 cpufreq_cooling_register(const struct cpumask *clip_cpus);
 
-/**
- * of_cpufreq_cooling_register - create cpufreq cooling device based on DT.
- * @np: a valid struct device_node to the cooling device device tree node.
- * @clip_cpus: cpumask of cpus where the frequency constraints will happen
- */
 #ifdef CONFIG_THERMAL_OF
 struct thermal_cooling_device *
 of_cpufreq_cooling_register(struct device_node *np,
@@ -54,10 +45,6 @@ of_cpufreq_cooling_register(struct device_node *np,
 }
 #endif
 
-/**
- * cpufreq_cooling_unregister - function to remove cpufreq cooling device.
- * @cdev: thermal cooling device pointer.
- */
 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev);
 
 unsigned long cpufreq_cooling_get_level(unsigned int cpu, unsigned int freq);
-- 
2.1.3

[PATCH RFC 04/12] thermal: of-thermal: remove kernel doc warn

[Eduardo Valentin]

The comment about trip type map is not a kernel doc
comment. Therefore, remove the kernel doc format,
so kernel doc won't complain.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 drivers/thermal/of-thermal.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/thermal/of-thermal.c b/drivers/thermal/of-thermal.c
index d717f3d..b66e3b2 100644
--- a/drivers/thermal/of-thermal.c
+++ b/drivers/thermal/of-thermal.c
@@ -621,7 +621,7 @@ end:
 	return ret;
 }
 
-/**
+/*
  * It maps 'enum thermal_trip_type' found in include/linux/thermal.h
  * into the device tree binding of 'trip', property type.
  */
-- 
2.1.3

[PATCH RFC 05/12] thermal: thermal.h: minor kernel doc fix

[Eduardo Valentin]

s/scallbacks/callbacks/g

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 include/linux/thermal.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index fc52e30..46c16a0 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -261,7 +261,7 @@ struct thermal_genl_event {
 };
 
 /**
- * struct thermal_zone_of_device_ops - scallbacks for handling DT based zones
+ * struct thermal_zone_of_device_ops - callbacks for handling DT based zones
  *
  * Mandatory:
  * @get_temp: a pointer to a function that reads the sensor temperature.
-- 
2.1.3

[PATCH RFC 06/12] thermal: thermal_core: correct kernel doc wording on thermal_zone_get_temp

[Eduardo Valentin]

Fix summary wording on thermal_zone_get_temp kernel doc.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 drivers/thermal/thermal_core.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/thermal/thermal_core.c b/drivers/thermal/thermal_core.c
index 87e0b07..846b68a 100644
--- a/drivers/thermal/thermal_core.c
+++ b/drivers/thermal/thermal_core.c
@@ -402,7 +402,7 @@ static void handle_thermal_trip(struct thermal_zone_device *tz, int trip)
 }
 
 /**
- * thermal_zone_get_temp() - returns its the temperature of thermal zone
+ * thermal_zone_get_temp() - returns the temperature of thermal zone
  * @tz: a valid pointer to a struct thermal_zone_device
  * @temp: a valid pointer to where to store the resulting temperature.
  *
-- 
2.1.3

[PATCH RFC 07/12] Documentation: thermal docbook: introduce API reference chapter

[Eduardo Valentin]

In this patch we add a chapter to contain the API reference
for the thermal framework. For now, we list the documented
functions from thermal core, cpu cooling, and of thermal.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 Documentation/DocBook/thermal.tmpl | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
index 66efed3..d6ebbea 100644
--- a/Documentation/DocBook/thermal.tmpl
+++ b/Documentation/DocBook/thermal.tmpl
@@ -212,4 +212,13 @@
 			</glossary>
 		</sect1>
 	</chapter>
+	<chapter id="api">
+	<title>Thermal Device Driver Writer API reference</title>
+		<para> This Chapter contains an API reference for Thermal driver writers.
+		</para>
+!Iinclude/linux/thermal.h
+!Edrivers/thermal/thermal_core.c
+!Edrivers/thermal/cpu_cooling.c
+!Edrivers/thermal/of-thermal.c
+	</chapter>
 </book>
-- 
2.1.3

[PATCH RFC 08/12] thermal: fair share: fix kernel doc entry

[Eduardo Valentin]

Update kernel doc entry and correct the format. Now
kernel doc does not complain about it.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 drivers/thermal/fair_share.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/drivers/thermal/fair_share.c b/drivers/thermal/fair_share.c
index 6e0a3fb..a15ef0b 100644
--- a/drivers/thermal/fair_share.c
+++ b/drivers/thermal/fair_share.c
@@ -70,7 +70,8 @@ static long get_target_state(struct thermal_zone_device *tz,
 
 /**
  * fair_share_throttle - throttles devices asscciated with the given zone
- * @tz - thermal_zone_device
+ * @tz: thermal_zone_device
+ * @trip: the trip point
  *
  * Throttling Logic: This uses three parameters to calculate the new
  * throttle state of the cooling devices associated with the given zone.
@@ -85,6 +86,8 @@ static long get_target_state(struct thermal_zone_device *tz,
  *	whereas the throttling is at full swing if we trip critical levels.
  *	(Heavily assumes the trip points are in ascending order)
  * new_state of cooling device = P3 * P2 * P1
+ *
+ * Return: 0.
  */
 static int fair_share_throttle(struct thermal_zone_device *tz, int trip)
 {
-- 
2.1.3

[PATCH RFC 09/12] thermal: user space: fix kernel doc entry

[Eduardo Valentin]

Update kernel doc entry and correct the format. Now
kernel doc does not complain about it.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 drivers/thermal/user_space.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/drivers/thermal/user_space.c b/drivers/thermal/user_space.c
index 10adcdd..29c91cb 100644
--- a/drivers/thermal/user_space.c
+++ b/drivers/thermal/user_space.c
@@ -28,9 +28,12 @@
 
 /**
  * notify_user_space - Notifies user space about thermal events
- * @tz - thermal_zone_device
+ * @tz: thermal_zone_device
+ * @trip: the trip point
  *
  * This function notifies the user space through UEvents.
+ *
+ * Return: 0.
  */
 static int notify_user_space(struct thermal_zone_device *tz, int trip)
 {
-- 
2.1.3

[PATCH RFC 10/12] thermal: bang bang: fix kernel doc entry

[Eduardo Valentin]

Update kernel doc entry and correct the format. Now
kernel doc does not complain about it.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 drivers/thermal/gov_bang_bang.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/drivers/thermal/gov_bang_bang.c b/drivers/thermal/gov_bang_bang.c
index c5dd76b..5154929 100644
--- a/drivers/thermal/gov_bang_bang.c
+++ b/drivers/thermal/gov_bang_bang.c
@@ -74,8 +74,8 @@ static void thermal_zone_trip_update(struct thermal_zone_device *tz, int trip)
 
 /**
  * bang_bang_control - controls devices associated with the given zone
- * @tz - thermal_zone_device
- * @trip - the trip point
+ * @tz: thermal_zone_device
+ * @trip: the trip point
  *
  * Regulation Logic: a two point regulation, deliver cooling state depending
  * on the previous state shown in this diagram:
@@ -98,6 +98,7 @@ static void thermal_zone_trip_update(struct thermal_zone_device *tz, int trip)
  *   * In case the fan is running, temperature must fall below
  *     (trip_temp - hyst) so that the fan gets turned off again.
  *
+ * Return: 0.
  */
 static int bang_bang_control(struct thermal_zone_device *tz, int trip)
 {
-- 
2.1.3

[PATCH RFC 11/12] thermal: step wise: fix kernel doc entry

[Eduardo Valentin]

Update kernel doc entry and correct the format. Now
kernel doc does not complain about it.

In this change we reuse the comment that explain the
algorithm as a kernel doc entry. However, blank lines
are added, otherwise it will appear in a single paragraph
in the kernel doc output.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 drivers/thermal/step_wise.c | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/drivers/thermal/step_wise.c b/drivers/thermal/step_wise.c
index fdd1f52..413ee30 100644
--- a/drivers/thermal/step_wise.c
+++ b/drivers/thermal/step_wise.c
@@ -27,22 +27,34 @@
 
 #include "thermal_core.h"
 
-/*
- * If the temperature is higher than a trip point,
+/**
+ * DOC: Algorithm
+ *
+ * If the temperature is higher than a trip point:
+ *
  *    a. if the trend is THERMAL_TREND_RAISING, use higher cooling
  *       state for this trip point
+ *
  *    b. if the trend is THERMAL_TREND_DROPPING, use lower cooling
  *       state for this trip point
+ *
  *    c. if the trend is THERMAL_TREND_RAISE_FULL, use upper limit
  *       for this trip point
+ *
  *    d. if the trend is THERMAL_TREND_DROP_FULL, use lower limit
  *       for this trip point
+ *
+ *
  * If the temperature is lower than a trip point,
+ *
  *    a. if the trend is THERMAL_TREND_RAISING, do nothing
+ *
  *    b. if the trend is THERMAL_TREND_DROPPING, use lower cooling
  *       state for this trip point, if the cooling state already
  *       equals lower limit, deactivate the thermal instance
+ *
  *    c. if the trend is THERMAL_TREND_RAISE_FULL, do nothing
+ *
  *    d. if the trend is THERMAL_TREND_DROP_FULL, use lower limit,
  *       if the cooling state already equals lower limit,
  *       deactive the thermal instance
@@ -169,16 +181,17 @@ static void thermal_zone_trip_update(struct thermal_zone_device *tz, int trip)
 }
 
 /**
- * step_wise_throttle - throttles devices asscciated with the given zone
- * @tz - thermal_zone_device
- * @trip - the trip point
- * @trip_type - type of the trip point
+ * step_wise_throttle - throttles devices associated with the given zone
+ * @tz: thermal_zone_device
+ * @trip: the trip point
  *
  * Throttling Logic: This uses the trend of the thermal zone to throttle.
  * If the thermal zone is 'heating up' this throttles all the cooling
  * devices associated with the zone and its particular trip point, by one
  * step. If the zone is 'cooling down' it brings back the performance of
  * the devices by one step.
+ *
+ * Return: 0.
  */
 static int step_wise_throttle(struct thermal_zone_device *tz, int trip)
 {
-- 
2.1.3

[PATCH RFC 12/12] Documentation: thermal docbook: introduce governor chapter

[Eduardo Valentin]

In this patch we add a chapter in the thermal docbook to
describe the existing governors. The chapter contains
one section per governor.

Each governor description includes the respective code documentation.
Each governor section contains a description of the governor
logic.

Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
---
 Documentation/DocBook/thermal.tmpl | 67 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
index d6ebbea..cf1a198 100644
--- a/Documentation/DocBook/thermal.tmpl
+++ b/Documentation/DocBook/thermal.tmpl
@@ -212,6 +212,73 @@
 			</glossary>
 		</sect1>
 	</chapter>
+
+	<chapter id="governors">
+		<title>Thermal Governors</title>
+		<para>
+		</para>
+
+		<sect1 id="step_wise">
+			<title>step_wise Thermal Governor</title>
+			<para>Step Wise uses the trend of the thermal zone to
+			throttle. If the thermal zone is 'heating up' this
+			throttles all the cooling devices associated with the
+			zone and its particular trip point, by one step. If the
+			zone is 'cooling down' it brings back the performance
+			of the devices by one step.
+			</para>
+!Idrivers/thermal/step_wise.c
+!Pdrivers/thermal/step_wise.c Algorithm
+		</sect1>
+		<sect1 id="fair_share">
+			<title>fair_share Thermal Governor</title>
+			<para>Fair Share Governor uses three parameters to
+			calculate the new throttle state of the cooling devices
+			associated with the given zone.  Parameters used for
+			Throttling:
+			</para>
+			<itemizedlist mark='opencircle'>
+				<listitem>P1. max_state: Maximum throttle state
+				exposed by the cooling device.</listitem>
+				<listitem>P2. weight[i]/100:</listitem>
+				<listitem>How 'effective' the 'i'th device is,
+				in cooling the given zone.</listitem>
+				<listitem>P3.
+				cur_trip_level/max_no_of_trips:</listitem>
+			</itemizedlist>
+			<para>This describes the extent to which the devices
+			should be throttled. We do not want to throttle too
+			much when we trip a lower temperature, whereas the
+			throttling is at full swing if we trip critical levels.
+			Heavily assumes the trip points are in ascending order
+			new_state of cooling device = P3 * P2 * P1.
+			</para>
+!Idrivers/thermal/fair_share.c
+		</sect1>
+		<sect1 id="bang_bang">
+			<title>bang_bang Thermal Governor</title>
+			<para>The Bang Bang Governor has a two point regulation
+			logic, deliver cooling state depending on the previous
+			state shown in this diagram: </para>
+			<para>If the fan is not running and temperature exceeds
+			trip_temp, the fan gets turned on. In case the fan is
+			running, temperature must fall below (trip_temp - hyst)
+			so that the fan gets turned off again.
+			</para>
+!Idrivers/thermal/gov_bang_bang.c
+		</sect1>
+		<sect1 id="user_space">
+			<title>user_space Thermal Governor</title>
+			<para> The User Space governor is outside the Kernel.
+			The Thermal Framework hands off the entire control to
+			userland if the User Space governor is assigned to a
+			thermal zone. A KOBJ_CHANGE UEvent notification is sent
+			to userland whenever a governor needs to take an
+			action.
+			</para>
+!Idrivers/thermal/user_space.c
+		</sect1>
+	</chapter>
 	<chapter id="api">
 	<title>Thermal Device Driver Writer API reference</title>
 		<para> This Chapter contains an API reference for Thermal driver writers.
-- 
2.1.3

Re: [PATCH RFC 01/12] Documentation: Introduce Linux Kernel Thermal Framework DocBook

[Randy Dunlap]

On 02/09/15 13:34, Eduardo Valentin wrote:

> +	<chapter id="introduction">
> +		<title>Introduction</title>
> +		<para>Thermal management is any method or technique implied to
> +		mitigate emergencies caused by operating devices within
> +		unsupported temperatures. The challenge consists of designing a

I would flip the ending of that sentence:
		                     caused by operating devices outside of
		supported temperatures.

> +		product keeping the junction temperature of the IC components.
> +		The operating temperature of IC components used on products must
> +		operate within their design limits. Besides, temperature towards
> +		device enclosure must be in a comfort level for the user.
> +		Therefore, thermal management, by the time of this writing,
> +		starts in very early device design phase. Managing thermal may
> +		involve different disciplines, at different stages, such as
> +		temperature monitoring, floorplanning, microarchitectural
> +		techniques, compiler techniques, OS techniques, liquid cooling,
> +		and thermal reliability or security. This document covers what
> +		the Linux Kernel Thermal Framework provides as abstraction to
> +		users with respect to thermal management.  
> +		</para>
> +		<para>One of the first proposals to provide a solution to cover
> +		the thermal problem appears in the Advanced Configuration and
> +		Power Interface (ACPI) specification. ACPI provides an open
> +		standard for device configuration and power management by the
> +		operating system. However, several computing devices which may
> +		have thermal issues in the market disregard the ACPI standard.
> +		Therefore, the Linux Kernel Thermal Framework has been designed
> +		to serve as abstraction for ACPI and non-ACPI systems. The core
> +		concepts applies in both types of systems. 
> +		</para>
> +		<para>The Linux Kernel Thermal Framework has a design which
> +		represents the different thermal constraints found in an

drop:		                                                      an^^

> +		end-products. The thermal constraints exist to serve different
> +		purposes. There two major types of thermal constraints. The

		          There are two

> +		first is related to components junction temperature. The second
> +		is related to the level of comfort while end users are handling
> +		devices.
> +		</para>
> +
> +  </chapter>
> +</book>
> 


-- 
~Randy

Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Randy Dunlap]

On 02/09/15 13:34, Eduardo Valentin wrote:
> This change introduces a section in the Introduction Chapter to
> list concepts used by the Thermal Framework.
> 
> Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> ---
>  Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
>  1 file changed, 128 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> index f8fb8a2..66efed3 100644
> --- a/Documentation/DocBook/thermal.tmpl
> +++ b/Documentation/DocBook/thermal.tmpl
> @@ -84,5 +84,132 @@
>  		devices.
>  		</para>
>  
> -  </chapter>
> +		<sect1 id="glossary">
> +			<title>Glossary</title>
> +			<para>The Linux Kernel Thermal Framework  uses a
> +			specific terminology to represent the entities involved
> +			in thermal constrained environments. This section
> +			summaries the terminology as dictionary. These terms are

			summarizes

> +			in use within the present document and in the source
> +			code of the Linux Kernel Thermal Framework.
> +			</para>
> +			<glossary>
> +				<glossentry>
> +					<glossterm>Thermal Zone</glossterm>
> +					<glossdef>
> +						<para>Thermal zones represent
> +						what is the current status of a
> +						thermal constrained zone in the
> +						hardware. The zone usually is a
> +						device or component. The status
> +						of a thermal zone is mainly with
> +						respect to temperature.
> +						Currently, the Linux Kernel
> +						Thermal Framework represents
> +						temperature in miliCelsius. The
> +						current abstraction covers for
> +						non negative temperatures and

						non-negative

> +						constraints.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Thermal Sensors</glossterm>
> +					<glossdef>
> +						<para>Thermal sensors provide
> +						temperature sensing capabilities
> +						on thermal zones. Typical
> +						devices are I2C ADC converters
> +						and bandgaps. These are nodes
> +						providing temperature data to
> +						thermal zones. Thermal sensor
> +						devices may control one or more
> +						internal sensors.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Trips Points</glossterm>

					           Trip Points

> +					<glossdef>
> +						<para>The trip node describes a
> +						point in the temperature domain
> +						in which the system takes an
> +						action. This item describes just
> +						the point, not the action. Trip
> +						points are represented as
> +						temperature in miliCelsius. The
> +						current abstraction covers for
> +						non negative temperatures.

						non-negative

> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Thermal Governor</glossterm>
> +					<glossdef>
> +						<para>Thermal Governors
> +						represent a policy to manage the
> +						thermal zone device temperature.
> +						The governor targets to keep
> +						temperature in an acceptable
> +						range which correlates to the
> +						power budget, while maximizing
> +						the performance. Governors can
> +						be implemented in Kernel Space
> +						or in User Space.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Thermal Cooling Device</glossterm>
> +					<glossdef>
> +						<para>Cooling devices provide
> +						control on power dissipation.
> +						There are essentially two ways
> +						to provide control on power
> +						dissipation. First is by means
> +						of regulating device
> +						performance, which is known as
> +						passive cooling. A typical
> +						passive cooling is a CPU that
> +						has dynamic voltage and
> +						frequency scaling (DVFS), and
> +						uses lower frequencies as
> +						cooling states. Second is by
> +						means of activating devices in
> +						order to remove the dissipated
> +						heat, which is known as active
> +						cooling, e.g. regulating fan
> +						speeds. In both cases, cooling
> +						devices shall have a way to
> +						determine the state of cooling
> +						in which the device is.
> +				</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Cooling State</glossterm>
> +					<glossdef>
> +						<para>Any cooling device has a
> +						range of cooling states (i.e.
> +						different levels of heat
> +						dissipation). For example a
> +						fan's cooling states correspond
> +						to the different fan speeds
> +						possible. Cooling states are
> +						referred to by single unsigned
> +						integers, where larger numbers
> +						mean greater heat dissipation.
> +						The precise set of cooling
> +						states associated with a device
> +						(as referred to be the
> +						cooling-min-state and
> +						cooling-max-state properties)
> +						should be defined in a
> +						particular device's binding.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +			</glossary>
> +		</sect1>
> +	</chapter>
>  </book>
> 


-- 
~Randy

Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Mikko Perttunen]

On 02/09/2015 11:34 PM, Eduardo Valentin wrote:
> This change introduces a section in the Introduction Chapter to
> list concepts used by the Thermal Framework.
>
> Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> ---
>   Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
>   1 file changed, 128 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> index f8fb8a2..66efed3 100644
> --- a/Documentation/DocBook/thermal.tmpl
> +++ b/Documentation/DocBook/thermal.tmpl
> @@ -84,5 +84,132 @@
>   		devices.
>   		</para>
>
> -  </chapter>
> +		<sect1 id="glossary">
> +			<title>Glossary</title>
> +			<para>The Linux Kernel Thermal Framework  uses a
> +			specific terminology to represent the entities involved
> +			in thermal constrained environments. This section
> +			summaries the terminology as dictionary. These terms are
> +			in use within the present document and in the source
> +			code of the Linux Kernel Thermal Framework.
> +			</para>
> +			<glossary>
> +				<glossentry>
> +					<glossterm>Thermal Zone</glossterm>
> +					<glossdef>
> +						<para>Thermal zones represent
> +						what is the current status of a
> +						thermal constrained zone in the
> +						hardware. The zone usually is a
> +						device or component. The status
> +						of a thermal zone is mainly with
> +						respect to temperature.
> +						Currently, the Linux Kernel
> +						Thermal Framework represents
> +						temperature in miliCelsius. The

milli-Celsius or millicelsius. Same change later too.

> +						current abstraction covers for
> +						non negative temperatures and
> +						constraints.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Thermal Sensors</glossterm>
> +					<glossdef>
> +						<para>Thermal sensors provide
> +						temperature sensing capabilities
> +						on thermal zones. Typical
> +						devices are I2C ADC converters
> +						and bandgaps. These are nodes
> +						providing temperature data to
> +						thermal zones. Thermal sensor
> +						devices may control one or more
> +						internal sensors.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Trips Points</glossterm>
> +					<glossdef>
> +						<para>The trip node describes a
> +						point in the temperature domain
> +						in which the system takes an
> +						action. This item describes just
> +						the point, not the action. Trip
> +						points are represented as
> +						temperature in miliCelsius. The

here

> +						current abstraction covers for
> +						non negative temperatures.

One thing I'd also like to see documented is the roles of the different 
trip types (PASSIVE, ACTIVE, HOT, CRITICAL) and when each should be used.

> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Thermal Governor</glossterm>
> +					<glossdef>
> +						<para>Thermal Governors
> +						represent a policy to manage the
> +						thermal zone device temperature.
> +						The governor targets to keep
> +						temperature in an acceptable
> +						range which correlates to the
> +						power budget, while maximizing
> +						the performance. Governors can
> +						be implemented in Kernel Space
> +						or in User Space.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Thermal Cooling Device</glossterm>
> +					<glossdef>
> +						<para>Cooling devices provide
> +						control on power dissipation.
> +						There are essentially two ways
> +						to provide control on power
> +						dissipation. First is by means
> +						of regulating device
> +						performance, which is known as
> +						passive cooling. A typical
> +						passive cooling is a CPU that
> +						has dynamic voltage and
> +						frequency scaling (DVFS), and
> +						uses lower frequencies as
> +						cooling states. Second is by
> +						means of activating devices in
> +						order to remove the dissipated
> +						heat, which is known as active
> +						cooling, e.g. regulating fan
> +						speeds. In both cases, cooling
> +						devices shall have a way to
> +						determine the state of cooling
> +						in which the device is.
> +				</para>
> +					</glossdef>
> +				</glossentry>
> +				<glossentry>
> +					<glossterm>Cooling State</glossterm>
> +					<glossdef>
> +						<para>Any cooling device has a
> +						range of cooling states (i.e.
> +						different levels of heat
> +						dissipation). For example a
> +						fan's cooling states correspond
> +						to the different fan speeds
> +						possible. Cooling states are
> +						referred to by single unsigned
> +						integers, where larger numbers
> +						mean greater heat dissipation.
> +						The precise set of cooling
> +						states associated with a device
> +						(as referred to be the
> +						cooling-min-state and
> +						cooling-max-state properties)
> +						should be defined in a
> +						particular device's binding.
> +						</para>
> +					</glossdef>
> +				</glossentry>
> +			</glossary>
> +		</sect1>
> +	</chapter>
>   </book>
>

Cheers,
Mikko.

Re: [PATCH RFC 01/12] Documentation: Introduce Linux Kernel Thermal Framework DocBook

[Eduardo Valentin]

[-- Attachment #1: Type: text/plain, Size: 2866 bytes --]

On Tue, Feb 10, 2015 at 02:50:36PM -0800, Randy Dunlap wrote:
> On 02/09/15 13:34, Eduardo Valentin wrote:
> 
> > +	<chapter id="introduction">
> > +		<title>Introduction</title>
> > +		<para>Thermal management is any method or technique implied to
> > +		mitigate emergencies caused by operating devices within
> > +		unsupported temperatures. The challenge consists of designing a
> 
> I would flip the ending of that sentence:
> 		                     caused by operating devices outside of
> 		supported temperatures.
> 
> > +		product keeping the junction temperature of the IC components.
> > +		The operating temperature of IC components used on products must
> > +		operate within their design limits. Besides, temperature towards
> > +		device enclosure must be in a comfort level for the user.
> > +		Therefore, thermal management, by the time of this writing,
> > +		starts in very early device design phase. Managing thermal may
> > +		involve different disciplines, at different stages, such as
> > +		temperature monitoring, floorplanning, microarchitectural
> > +		techniques, compiler techniques, OS techniques, liquid cooling,
> > +		and thermal reliability or security. This document covers what
> > +		the Linux Kernel Thermal Framework provides as abstraction to
> > +		users with respect to thermal management.  
> > +		</para>
> > +		<para>One of the first proposals to provide a solution to cover
> > +		the thermal problem appears in the Advanced Configuration and
> > +		Power Interface (ACPI) specification. ACPI provides an open
> > +		standard for device configuration and power management by the
> > +		operating system. However, several computing devices which may
> > +		have thermal issues in the market disregard the ACPI standard.
> > +		Therefore, the Linux Kernel Thermal Framework has been designed
> > +		to serve as abstraction for ACPI and non-ACPI systems. The core
> > +		concepts applies in both types of systems. 
> > +		</para>
> > +		<para>The Linux Kernel Thermal Framework has a design which
> > +		represents the different thermal constraints found in an
> 
> drop:		                                                      an^^
> 
> > +		end-products. The thermal constraints exist to serve different
> > +		purposes. There two major types of thermal constraints. The
> 
> 		          There are two
> 
> > +		first is related to components junction temperature. The second
> > +		is related to the level of comfort while end users are handling
> > +		devices.
> > +		</para>
> > +
> > +  </chapter>
> > +</book>
> > 
> 
> 
> -- 
> ~Randy

Thanks Randy for checking this up. I apologize for forgetting Ccing you
in my original post. I will fix the text as per your suggestions and
also copy you in next version.

Thanks for you time.

Eduardo Valentin


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 473 bytes --]

Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Eduardo Valentin]

[-- Attachment #1: Type: text/plain, Size: 5725 bytes --]

Randy

On Tue, Feb 10, 2015 at 02:50:47PM -0800, Randy Dunlap wrote:
> On 02/09/15 13:34, Eduardo Valentin wrote:
> > This change introduces a section in the Introduction Chapter to
> > list concepts used by the Thermal Framework.
> > 
> > Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> > ---
> >  Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 128 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> > index f8fb8a2..66efed3 100644
> > --- a/Documentation/DocBook/thermal.tmpl
> > +++ b/Documentation/DocBook/thermal.tmpl
> > @@ -84,5 +84,132 @@
> >  		devices.
> >  		</para>
> >  
> > -  </chapter>
> > +		<sect1 id="glossary">
> > +			<title>Glossary</title>
> > +			<para>The Linux Kernel Thermal Framework  uses a
> > +			specific terminology to represent the entities involved
> > +			in thermal constrained environments. This section
> > +			summaries the terminology as dictionary. These terms are
> 
> 			summarizes
> 
> > +			in use within the present document and in the source
> > +			code of the Linux Kernel Thermal Framework.
> > +			</para>
> > +			<glossary>
> > +				<glossentry>
> > +					<glossterm>Thermal Zone</glossterm>
> > +					<glossdef>
> > +						<para>Thermal zones represent
> > +						what is the current status of a
> > +						thermal constrained zone in the
> > +						hardware. The zone usually is a
> > +						device or component. The status
> > +						of a thermal zone is mainly with
> > +						respect to temperature.
> > +						Currently, the Linux Kernel
> > +						Thermal Framework represents
> > +						temperature in miliCelsius. The
> > +						current abstraction covers for
> > +						non negative temperatures and
> 
> 						non-negative
> 
> > +						constraints.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Thermal Sensors</glossterm>
> > +					<glossdef>
> > +						<para>Thermal sensors provide
> > +						temperature sensing capabilities
> > +						on thermal zones. Typical
> > +						devices are I2C ADC converters
> > +						and bandgaps. These are nodes
> > +						providing temperature data to
> > +						thermal zones. Thermal sensor
> > +						devices may control one or more
> > +						internal sensors.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Trips Points</glossterm>
> 
> 					           Trip Points
> 
> > +					<glossdef>
> > +						<para>The trip node describes a
> > +						point in the temperature domain
> > +						in which the system takes an
> > +						action. This item describes just
> > +						the point, not the action. Trip
> > +						points are represented as
> > +						temperature in miliCelsius. The
> > +						current abstraction covers for
> > +						non negative temperatures.
> 
> 						non-negative
> 
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Thermal Governor</glossterm>
> > +					<glossdef>
> > +						<para>Thermal Governors
> > +						represent a policy to manage the
> > +						thermal zone device temperature.
> > +						The governor targets to keep
> > +						temperature in an acceptable
> > +						range which correlates to the
> > +						power budget, while maximizing
> > +						the performance. Governors can
> > +						be implemented in Kernel Space
> > +						or in User Space.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Thermal Cooling Device</glossterm>
> > +					<glossdef>
> > +						<para>Cooling devices provide
> > +						control on power dissipation.
> > +						There are essentially two ways
> > +						to provide control on power
> > +						dissipation. First is by means
> > +						of regulating device
> > +						performance, which is known as
> > +						passive cooling. A typical
> > +						passive cooling is a CPU that
> > +						has dynamic voltage and
> > +						frequency scaling (DVFS), and
> > +						uses lower frequencies as
> > +						cooling states. Second is by
> > +						means of activating devices in
> > +						order to remove the dissipated
> > +						heat, which is known as active
> > +						cooling, e.g. regulating fan
> > +						speeds. In both cases, cooling
> > +						devices shall have a way to
> > +						determine the state of cooling
> > +						in which the device is.
> > +				</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Cooling State</glossterm>
> > +					<glossdef>
> > +						<para>Any cooling device has a
> > +						range of cooling states (i.e.
> > +						different levels of heat
> > +						dissipation). For example a
> > +						fan's cooling states correspond
> > +						to the different fan speeds
> > +						possible. Cooling states are
> > +						referred to by single unsigned
> > +						integers, where larger numbers
> > +						mean greater heat dissipation.
> > +						The precise set of cooling
> > +						states associated with a device
> > +						(as referred to be the
> > +						cooling-min-state and
> > +						cooling-max-state properties)
> > +						should be defined in a
> > +						particular device's binding.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +			</glossary>
> > +		</sect1>
> > +	</chapter>
> >  </book>
> > 
> 
> 
> -- 
> ~Randy


Fixing all the above in next version.

Thanks,

Eduardo Valentin

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 473 bytes --]

Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Eduardo Valentin]

[-- Attachment #1: Type: text/plain, Size: 6022 bytes --]

Terve Mikko,

On Mon, Feb 16, 2015 at 03:01:25PM +0200, Mikko Perttunen wrote:
> On 02/09/2015 11:34 PM, Eduardo Valentin wrote:
> > This change introduces a section in the Introduction Chapter to
> > list concepts used by the Thermal Framework.
> >
> > Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> > ---
> >   Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
> >   1 file changed, 128 insertions(+), 1 deletion(-)
> >
> > diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> > index f8fb8a2..66efed3 100644
> > --- a/Documentation/DocBook/thermal.tmpl
> > +++ b/Documentation/DocBook/thermal.tmpl
> > @@ -84,5 +84,132 @@
> >   		devices.
> >   		</para>
> >
> > -  </chapter>
> > +		<sect1 id="glossary">
> > +			<title>Glossary</title>
> > +			<para>The Linux Kernel Thermal Framework  uses a
> > +			specific terminology to represent the entities involved
> > +			in thermal constrained environments. This section
> > +			summaries the terminology as dictionary. These terms are
> > +			in use within the present document and in the source
> > +			code of the Linux Kernel Thermal Framework.
> > +			</para>
> > +			<glossary>
> > +				<glossentry>
> > +					<glossterm>Thermal Zone</glossterm>
> > +					<glossdef>
> > +						<para>Thermal zones represent
> > +						what is the current status of a
> > +						thermal constrained zone in the
> > +						hardware. The zone usually is a
> > +						device or component. The status
> > +						of a thermal zone is mainly with
> > +						respect to temperature.
> > +						Currently, the Linux Kernel
> > +						Thermal Framework represents
> > +						temperature in miliCelsius. The
> 
> milli-Celsius or millicelsius. Same change later too.

OK. I will standardize.

> 
> > +						current abstraction covers for
> > +						non negative temperatures and
> > +						constraints.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Thermal Sensors</glossterm>
> > +					<glossdef>
> > +						<para>Thermal sensors provide
> > +						temperature sensing capabilities
> > +						on thermal zones. Typical
> > +						devices are I2C ADC converters
> > +						and bandgaps. These are nodes
> > +						providing temperature data to
> > +						thermal zones. Thermal sensor
> > +						devices may control one or more
> > +						internal sensors.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Trips Points</glossterm>
> > +					<glossdef>
> > +						<para>The trip node describes a
> > +						point in the temperature domain
> > +						in which the system takes an
> > +						action. This item describes just
> > +						the point, not the action. Trip
> > +						points are represented as
> > +						temperature in miliCelsius. The
> 
> here
> 
> > +						current abstraction covers for
> > +						non negative temperatures.
> 
> One thing I'd also like to see documented is the roles of the different 
> trip types (PASSIVE, ACTIVE, HOT, CRITICAL) and when each should be used.

OK. That makes sense to me. I will include either a chapter about
thermal zones and have a section about it, or include in here, in the
glossary. I will think about it.

Thanks for your thoughts!

> 
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Thermal Governor</glossterm>
> > +					<glossdef>
> > +						<para>Thermal Governors
> > +						represent a policy to manage the
> > +						thermal zone device temperature.
> > +						The governor targets to keep
> > +						temperature in an acceptable
> > +						range which correlates to the
> > +						power budget, while maximizing
> > +						the performance. Governors can
> > +						be implemented in Kernel Space
> > +						or in User Space.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Thermal Cooling Device</glossterm>
> > +					<glossdef>
> > +						<para>Cooling devices provide
> > +						control on power dissipation.
> > +						There are essentially two ways
> > +						to provide control on power
> > +						dissipation. First is by means
> > +						of regulating device
> > +						performance, which is known as
> > +						passive cooling. A typical
> > +						passive cooling is a CPU that
> > +						has dynamic voltage and
> > +						frequency scaling (DVFS), and
> > +						uses lower frequencies as
> > +						cooling states. Second is by
> > +						means of activating devices in
> > +						order to remove the dissipated
> > +						heat, which is known as active
> > +						cooling, e.g. regulating fan
> > +						speeds. In both cases, cooling
> > +						devices shall have a way to
> > +						determine the state of cooling
> > +						in which the device is.
> > +				</para>
> > +					</glossdef>
> > +				</glossentry>
> > +				<glossentry>
> > +					<glossterm>Cooling State</glossterm>
> > +					<glossdef>
> > +						<para>Any cooling device has a
> > +						range of cooling states (i.e.
> > +						different levels of heat
> > +						dissipation). For example a
> > +						fan's cooling states correspond
> > +						to the different fan speeds
> > +						possible. Cooling states are
> > +						referred to by single unsigned
> > +						integers, where larger numbers
> > +						mean greater heat dissipation.
> > +						The precise set of cooling
> > +						states associated with a device
> > +						(as referred to be the
> > +						cooling-min-state and
> > +						cooling-max-state properties)
> > +						should be defined in a
> > +						particular device's binding.
> > +						</para>
> > +					</glossdef>
> > +				</glossentry>
> > +			</glossary>
> > +		</sect1>
> > +	</chapter>
> >   </book>
> >
> 
> Cheers,
> Mikko.
> 

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 473 bytes --]

Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Eduardo Valentin]

[-- Attachment #1: Type: text/plain, Size: 3682 bytes --]

On Wed, Feb 18, 2015 at 08:58:18AM -0800, Srinivas Pandruvada wrote:
> On Wed, 2015-02-18 at 11:52 +0000, Javi Merino wrote: 
> > Hi Eduardo,
> > 
> > On Mon, Feb 09, 2015 at 09:34:03PM +0000, Eduardo Valentin wrote:
> > > This change introduces a section in the Introduction Chapter to
> > > list concepts used by the Thermal Framework.
> > > 
> > > Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> > > ---
> > >  Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
> > >  1 file changed, 128 insertions(+), 1 deletion(-)
> > > 
> > > diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> > > index f8fb8a2..66efed3 100644
> > > --- a/Documentation/DocBook/thermal.tmpl
> > > +++ b/Documentation/DocBook/thermal.tmpl
> > > @@ -84,5 +84,132 @@
> > >  		devices.
> > >  		</para>
> > >  
> > > -  </chapter>
> > > +		<sect1 id="glossary">
> > > +			<title>Glossary</title>
> > > +			<para>The Linux Kernel Thermal Framework  uses a
> > > +			specific terminology to represent the entities involved
> > > +			in thermal constrained environments. This section
> > > +			summaries the terminology as dictionary. These terms are
> > > +			in use within the present document and in the source
> > > +			code of the Linux Kernel Thermal Framework.
> > > +			</para>
> > > +			<glossary>
> > > +				<glossentry>
> > > +					<glossterm>Thermal Zone</glossterm>
> > > +					<glossdef>
> > > +						<para>Thermal zones represent
> > > +						what is the current status of a
> > > +						thermal constrained zone in the
> > > +						hardware. The zone usually is a
> > > +						device or component. The status
> > > +						of a thermal zone is mainly with
> > > +						respect to temperature.
> > > +						Currently, the Linux Kernel
> > > +						Thermal Framework represents
> > > +						temperature in miliCelsius. The
> > > +						current abstraction covers for
> > > +						non negative temperatures and
> > > +						constraints.
> > > +						</para>
> > 
> > Shall we point out that a thermal zone doesn't necessarily imply a
> > thermal sensor?  I find it very common to assume that if you have 10
> > sensors, you should have 10 thermal zones.  From my point of view, a
> > thermal zone is an area that has similar thermal characteristics.
> > Therefore, the temperature of the thermal zone doesn't necessarily
> > have to come from on sensor, and can be defined as a combination of
> > the input from multiple thermal sensors.

Yes, I agree that here we should mention that we are talking about an
area/zone in hardware.

> 
> Currently since you can have one temperature input per zone
> (irrespective of whether the temperature is combination of many sensors
> or virtual sensor), so separating thermal sensor and zone can be more
> confusing IMO from a user space perspective.

I believe we should make it clear in the documentation what is the
relation between each entity. I will add a section about the relations,
clarifying from concept perspective, implementation wise, and from
userspace perspective.

> 
> This was a feature proposed and submitted for thermal sysfs 2.0 (or next
> version), where sensors and zones are separated. I think there was some
> plan to adopt this. Rui Zhang can comment more.

Yes, I agree. However, the sysfs 2.0 never made upstream. The current
documentation project targets what is in the kernel tree.

> 
> Thanks,
> Srinivas
> 
> 
> > 
> > I don't know how to put this in proper words for the documentation,
> > but I think it's worth hinting it here.
> > 
> > Cheers,
> > Javi
> 
> 

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 473 bytes --]

Re: [PATCH RFC 01/12] Documentation: Introduce Linux Kernel Thermal Framework DocBook

[Javi Merino]

On Mon, Feb 09, 2015 at 09:34:02PM +0000, Eduardo Valentin wrote:
> This patch adds a book about the Linux Kernel Thermal Framework.
> In this change, only a brief introduction is added together with
> Makefile changes.
> 
> Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> ---
>  Documentation/DocBook/Makefile     |  3 +-
>  Documentation/DocBook/thermal.tmpl | 88 ++++++++++++++++++++++++++++++++++++++
>  2 files changed, 90 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/DocBook/thermal.tmpl
> 
> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
> index 9c7d92d..8163508 100644
> --- a/Documentation/DocBook/Makefile
> +++ b/Documentation/DocBook/Makefile
> @@ -15,7 +15,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
>  	    80211.xml debugobjects.xml sh.xml regulator.xml \
>  	    alsa-driver-api.xml writing-an-alsa-driver.xml \
>  	    tracepoint.xml drm.xml media_api.xml w1.xml \
> -	    writing_musb_glue_layer.xml crypto-API.xml
> +	    writing_musb_glue_layer.xml crypto-API.xml thermal.xml
> +	    writing_musb_glue_layer.xml

Duplicated writing_musb_glue_layer.xml ?  Looks like the second line
should be removed.

>  
>  include Documentation/DocBook/media/Makefile
>  
> diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> new file mode 100644
> index 0000000..f8fb8a2
> --- /dev/null
> +++ b/Documentation/DocBook/thermal.tmpl
> @@ -0,0 +1,88 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> +	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
> +
> +<book id="thermal-api">
> + <bookinfo>
> +  <title>Linux Kernel Thermal Framework API</title>
> +
> +  <authorgroup>
> +   <author>
> +    <firstname>Eduardo</firstname>
> +    <surname>Valentin</surname>
> +    <affiliation>
> +     <address>
> +      <email>evalenti@kernel.org</email>
> +     </address>
> +    </affiliation>
> +   </author>
> +  </authorgroup>
> +
> +  <copyright>
> +   <year>2008-2014</year>
> +   <holder>Eduardo Valentin</holder>
> +   <holder>Sujith Thomas</holder>
> +   <holder>Zhang Rui</holder>
> +  </copyright>
> +  <legalnotice>
> +   <para>
> +     This documentation is free software; you can redistribute
> +     it and/or modify it under the terms of the GNU General Public
> +     License version 2 as published by the Free Software Foundation.
> +   </para>
> +
> +   <para>
> +     This program is distributed in the hope that it will be
> +     useful, but WITHOUT ANY WARRANTY; without even the implied
> +     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> +     See the GNU General Public License for more details.
> +   </para>
> +
> +   <para>
> +     For more details see the file COPYING in the source
> +     distribution of Linux.
> +   </para>
> +  </legalnotice>
> + </bookinfo>
> +
> +<toc></toc>
> +
> +	<chapter id="introduction">
> +		<title>Introduction</title>
> +		<para>Thermal management is any method or technique implied to
> +		mitigate emergencies caused by operating devices within
> +		unsupported temperatures. The challenge consists of designing a
> +		product keeping the junction temperature of the IC components.
> +		The operating temperature of IC components used on products must
> +		operate within their design limits. Besides, temperature towards
> +		device enclosure must be in a comfort level for the user.
> +		Therefore, thermal management, by the time of this writing,
> +		starts in very early device design phase. Managing thermal may
> +		involve different disciplines, at different stages, such as
> +		temperature monitoring, floorplanning, microarchitectural
> +		techniques, compiler techniques, OS techniques, liquid cooling,
> +		and thermal reliability or security. This document covers what
> +		the Linux Kernel Thermal Framework provides as abstraction to
> +		users with respect to thermal management.  
> +		</para>
> +		<para>One of the first proposals to provide a solution to cover
> +		the thermal problem appears in the Advanced Configuration and
> +		Power Interface (ACPI) specification. ACPI provides an open
> +		standard for device configuration and power management by the
> +		operating system. However, several computing devices which may
> +		have thermal issues in the market disregard the ACPI standard.
> +		Therefore, the Linux Kernel Thermal Framework has been designed
> +		to serve as abstraction for ACPI and non-ACPI systems. The core
> +		concepts applies in both types of systems. 
> +		</para>
> +		<para>The Linux Kernel Thermal Framework has a design which
> +		represents the different thermal constraints found in an
> +		end-products. The thermal constraints exist to serve different
> +		purposes. There two major types of thermal constraints. The
                                are

> +		first is related to components junction temperature. The second
> +		is related to the level of comfort while end users are handling
> +		devices.
> +		</para>
> +
> +  </chapter>
> +</book>

Cheers,
Javi

Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Javi Merino]

Hi Eduardo,

On Mon, Feb 09, 2015 at 09:34:03PM +0000, Eduardo Valentin wrote:
> This change introduces a section in the Introduction Chapter to
> list concepts used by the Thermal Framework.
> 
> Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> ---
>  Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
>  1 file changed, 128 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> index f8fb8a2..66efed3 100644
> --- a/Documentation/DocBook/thermal.tmpl
> +++ b/Documentation/DocBook/thermal.tmpl
> @@ -84,5 +84,132 @@
>  		devices.
>  		</para>
>  
> -  </chapter>
> +		<sect1 id="glossary">
> +			<title>Glossary</title>
> +			<para>The Linux Kernel Thermal Framework  uses a
> +			specific terminology to represent the entities involved
> +			in thermal constrained environments. This section
> +			summaries the terminology as dictionary. These terms are
> +			in use within the present document and in the source
> +			code of the Linux Kernel Thermal Framework.
> +			</para>
> +			<glossary>
> +				<glossentry>
> +					<glossterm>Thermal Zone</glossterm>
> +					<glossdef>
> +						<para>Thermal zones represent
> +						what is the current status of a
> +						thermal constrained zone in the
> +						hardware. The zone usually is a
> +						device or component. The status
> +						of a thermal zone is mainly with
> +						respect to temperature.
> +						Currently, the Linux Kernel
> +						Thermal Framework represents
> +						temperature in miliCelsius. The
> +						current abstraction covers for
> +						non negative temperatures and
> +						constraints.
> +						</para>

Shall we point out that a thermal zone doesn't necessarily imply a
thermal sensor?  I find it very common to assume that if you have 10
sensors, you should have 10 thermal zones.  From my point of view, a
thermal zone is an area that has similar thermal characteristics.
Therefore, the temperature of the thermal zone doesn't necessarily
have to come from on sensor, and can be defined as a combination of
the input from multiple thermal sensors.

I don't know how to put this in proper words for the documentation,
but I think it's worth hinting it here.

Cheers,
Javi

Re: [PATCH RFC 12/12] Documentation: thermal docbook: introduce governor chapter

[Javi Merino]

Hi Eduardo,

On Mon, Feb 09, 2015 at 09:34:13PM +0000, Eduardo Valentin wrote:
> In this patch we add a chapter in the thermal docbook to
> describe the existing governors. The chapter contains
> one section per governor.
> 
> Each governor description includes the respective code documentation.
> Each governor section contains a description of the governor
> logic.
> 
> Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> ---
>  Documentation/DocBook/thermal.tmpl | 67 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 67 insertions(+)
> 
> diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> index d6ebbea..cf1a198 100644
> --- a/Documentation/DocBook/thermal.tmpl
> +++ b/Documentation/DocBook/thermal.tmpl
> @@ -212,6 +212,73 @@
>  			</glossary>
>  		</sect1>
>  	</chapter>
> +
> +	<chapter id="governors">
> +		<title>Thermal Governors</title>
> +		<para>
> +		</para>
> +
> +		<sect1 id="step_wise">
> +			<title>step_wise Thermal Governor</title>
> +			<para>Step Wise uses the trend of the thermal zone to
> +			throttle. If the thermal zone is 'heating up' this
> +			throttles all the cooling devices associated with the
> +			zone and its particular trip point, by one step. If the
> +			zone is 'cooling down' it brings back the performance
> +			of the devices by one step.
> +			</para>
> +!Idrivers/thermal/step_wise.c
> +!Pdrivers/thermal/step_wise.c Algorithm
> +		</sect1>
> +		<sect1 id="fair_share">
> +			<title>fair_share Thermal Governor</title>
> +			<para>Fair Share Governor uses three parameters to
> +			calculate the new throttle state of the cooling devices
> +			associated with the given zone.  Parameters used for
> +			Throttling:
> +			</para>
> +			<itemizedlist mark='opencircle'>
> +				<listitem>P1. max_state: Maximum throttle state
> +				exposed by the cooling device.</listitem>
> +				<listitem>P2. weight[i]/100:</listitem>
> +				<listitem>How 'effective' the 'i'th device is,
> +				in cooling the given zone.</listitem>
> +				<listitem>P3.
> +				cur_trip_level/max_no_of_trips:</listitem>
> +			</itemizedlist>
> +			<para>This describes the extent to which the devices
> +			should be throttled. We do not want to throttle too
> +			much when we trip a lower temperature, whereas the
> +			throttling is at full swing if we trip critical levels.
> +			Heavily assumes the trip points are in ascending order
> +			new_state of cooling device = P3 * P2 * P1.
> +			</para>

This seems to be heavily based on the kerneldoc in fair_share.c .
Wouldn't it be better to do a similar trick to what you did in
step_wise?  That is, move that kerneldoc into an "Algorithm" entry and
include it here.  That way we avoid the duplication of the
documentation.

Cheers,
Javi

> +!Idrivers/thermal/fair_share.c
> +		</sect1>
> +		<sect1 id="bang_bang">
> +			<title>bang_bang Thermal Governor</title>
> +			<para>The Bang Bang Governor has a two point regulation
> +			logic, deliver cooling state depending on the previous
> +			state shown in this diagram: </para>
> +			<para>If the fan is not running and temperature exceeds
> +			trip_temp, the fan gets turned on. In case the fan is
> +			running, temperature must fall below (trip_temp - hyst)
> +			so that the fan gets turned off again.
> +			</para>
> +!Idrivers/thermal/gov_bang_bang.c
> +		</sect1>
> +		<sect1 id="user_space">
> +			<title>user_space Thermal Governor</title>
> +			<para> The User Space governor is outside the Kernel.
> +			The Thermal Framework hands off the entire control to
> +			userland if the User Space governor is assigned to a
> +			thermal zone. A KOBJ_CHANGE UEvent notification is sent
> +			to userland whenever a governor needs to take an
> +			action.
> +			</para>
> +!Idrivers/thermal/user_space.c
> +		</sect1>
> +	</chapter>
>  	<chapter id="api">
>  	<title>Thermal Device Driver Writer API reference</title>
>  		<para> This Chapter contains an API reference for Thermal driver writers.
> -- 
> 2.1.3
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-pm" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

[Srinivas Pandruvada]

On Wed, 2015-02-18 at 11:52 +0000, Javi Merino wrote: 
> Hi Eduardo,
> 
> On Mon, Feb 09, 2015 at 09:34:03PM +0000, Eduardo Valentin wrote:
> > This change introduces a section in the Introduction Chapter to
> > list concepts used by the Thermal Framework.
> > 
> > Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
> > ---
> >  Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 128 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> > index f8fb8a2..66efed3 100644
> > --- a/Documentation/DocBook/thermal.tmpl
> > +++ b/Documentation/DocBook/thermal.tmpl
> > @@ -84,5 +84,132 @@
> >  		devices.
> >  		</para>
> >  
> > -  </chapter>
> > +		<sect1 id="glossary">
> > +			<title>Glossary</title>
> > +			<para>The Linux Kernel Thermal Framework  uses a
> > +			specific terminology to represent the entities involved
> > +			in thermal constrained environments. This section
> > +			summaries the terminology as dictionary. These terms are
> > +			in use within the present document and in the source
> > +			code of the Linux Kernel Thermal Framework.
> > +			</para>
> > +			<glossary>
> > +				<glossentry>
> > +					<glossterm>Thermal Zone</glossterm>
> > +					<glossdef>
> > +						<para>Thermal zones represent
> > +						what is the current status of a
> > +						thermal constrained zone in the
> > +						hardware. The zone usually is a
> > +						device or component. The status
> > +						of a thermal zone is mainly with
> > +						respect to temperature.
> > +						Currently, the Linux Kernel
> > +						Thermal Framework represents
> > +						temperature in miliCelsius. The
> > +						current abstraction covers for
> > +						non negative temperatures and
> > +						constraints.
> > +						</para>
> 
> Shall we point out that a thermal zone doesn't necessarily imply a
> thermal sensor?  I find it very common to assume that if you have 10
> sensors, you should have 10 thermal zones.  From my point of view, a
> thermal zone is an area that has similar thermal characteristics.
> Therefore, the temperature of the thermal zone doesn't necessarily
> have to come from on sensor, and can be defined as a combination of
> the input from multiple thermal sensors.

Currently since you can have one temperature input per zone
(irrespective of whether the temperature is combination of many sensors
or virtual sensor), so separating thermal sensor and zone can be more
confusing IMO from a user space perspective.

This was a feature proposed and submitted for thermal sysfs 2.0 (or next
version), where sensors and zones are separated. I think there was some
plan to adopt this. Rui Zhang can comment more.

Thanks,
Srinivas


> 
> I don't know how to put this in proper words for the documentation,
> but I think it's worth hinting it here.
> 
> Cheers,
> Javi