Skip to contentSkip to conversation

The Linux Kernel Thermal Framework Docbook

RFC PATCH In review Eduardo Valentin 5 participants 24 messages Feb 9, 2015 – Feb 18, 2015

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

cover The Linux Kernel Thermal Framework Docbook

(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
Signature · 1 line
2.1.3
#1 lore raw

RFC PATCH 1/12 Documentation: Introduce Linux Kernel Thermal Framework DocBook

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

---
 Documentation/DocBook/Makefile     |  3 +-
 Documentation/DocBook/thermal.tmpl | 88 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/DocBook/thermal.tmpl
Documentation/DocBook/Makefile +2 -1
index 9c7d92d..8163508 100644
@@ -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
 
Documentation/DocBook/thermal.tmpl new file +88 -0

88 lines not on this page · raw message

Signature · 1 line
2.1.3
reviewer
#2 lore raw

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

Documentation/DocBook/thermal.tmpl line 54

Quoted 5 lines · Eduardo Valentin
Documentation/DocBook/thermal.tmpl new file +5 -0
+	<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.

Quoted 15 lines
Documentation/DocBook/thermal.tmpl new file +15 -0
+		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

Documentation/DocBook/thermal.tmpl line 79

Quoted 10 lines
Documentation/DocBook/thermal.tmpl new file +10 -0
+		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^^

Documentation/DocBook/thermal.tmpl line 81

Quoted 2 lines
Documentation/DocBook/thermal.tmpl new file +2 -0
+		end-products. The thermal constraints exist to serve different
+		purposes. There two major types of thermal constraints. The

There are two

Quoted 8 lines
Documentation/DocBook/thermal.tmpl new file +7 -0
+		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>
Signature · 1 line
~Randy
#3 lore raw

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

Quoted 45 lines · Randy Dunlap

Documentation/DocBook/thermal.tmpl line 54

Quoted 5 lines · Eduardo Valentin
Documentation/DocBook/thermal.tmpl new file +5 -0
+	<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.

Quoted 15 lines
Documentation/DocBook/thermal.tmpl new file +15 -0
+		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

Documentation/DocBook/thermal.tmpl line 79

Quoted 10 lines
Documentation/DocBook/thermal.tmpl new file +10 -0
+		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^^

Documentation/DocBook/thermal.tmpl line 81

Quoted 2 lines
Documentation/DocBook/thermal.tmpl new file +2 -0
+		end-products. The thermal constraints exist to serve different
+		purposes. There two major types of thermal constraints. The

There are two

Quoted 12 lines
Quoted 8 lines
Documentation/DocBook/thermal.tmpl new file +7 -0
+		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>
Signature · 1 line
~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

#4 lore raw

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

In reply to Eduardo Valentin
Quoted 16 lines · 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.

---
 Documentation/DocBook/Makefile     |  3 +-
 Documentation/DocBook/thermal.tmpl | 88 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/DocBook/thermal.tmpl
Documentation/DocBook/Makefile +0 -0
index 9c7d92d..8163508 100644

Documentation/DocBook/Makefile DOCBOOKS := z8530book.xml device-drivers.xml \ · line 19

Quoted 6 lines
Documentation/DocBook/Makefile +2 -1
@@ -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.

Quoted 80 lines
Documentation/DocBook/Makefile +0 -0
 include Documentation/DocBook/media/Makefile
 
Documentation/DocBook/thermal.tmpl new file +71 -0
new file mode 100644
index 0000000..f8fb8a2
@@ -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>[email protected]</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

Documentation/DocBook/thermal.tmpl line 81

Quoted 10 lines
Documentation/DocBook/thermal.tmpl new file +10 -0
+		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

Documentation/DocBook/thermal.tmpl line 88

Quoted 7 lines
Documentation/DocBook/thermal.tmpl new file +7 -0
+		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

#5 lore raw

RFC PATCH 2/12 Documentation: thermal docbook: add glossary

In reply to Eduardo Valentin

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

---
 Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +128 -1
index f8fb8a2..66efed3 100644
@@ -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>
Signature · 1 line
2.1.3
reviewer
#6 lore raw

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

Quoted 13 lines · Eduardo Valentin

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

---
 Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +0 -0
index f8fb8a2..66efed3 100644

Documentation/DocBook/thermal.tmpl line 92

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +6 -1
@@ -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

Quoted 9 lines
Documentation/DocBook/thermal.tmpl +9 -0
+			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

Documentation/DocBook/thermal.tmpl line 111

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+						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

Quoted 11 lines
Documentation/DocBook/thermal.tmpl +11 -0
+						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

Documentation/DocBook/thermal.tmpl line 132

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+						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

Documentation/DocBook/thermal.tmpl line 142

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+					<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

Quoted 74 lines
Documentation/DocBook/thermal.tmpl +72 -0
+						</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>
Signature · 1 line
~Randy
#7 lore raw

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

Randy

Quoted 152 lines · Randy Dunlap
Quoted 13 lines · Eduardo Valentin

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

---
 Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +0 -0
index f8fb8a2..66efed3 100644

Documentation/DocBook/thermal.tmpl line 92

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +6 -1
@@ -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

Quoted 9 lines
Documentation/DocBook/thermal.tmpl +9 -0
+			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

Documentation/DocBook/thermal.tmpl line 111

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+						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

Quoted 11 lines
Documentation/DocBook/thermal.tmpl +11 -0
+						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

Documentation/DocBook/thermal.tmpl line 132

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+						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

Documentation/DocBook/thermal.tmpl line 142

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+					<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

Quoted 66 lines
Documentation/DocBook/thermal.tmpl +66 -0
+						</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.
Quoted 12 lines
Quoted 8 lines
Documentation/DocBook/thermal.tmpl +6 -0
+						</para>
+					</glossdef>
+				</glossentry>
+			</glossary>
+		</sect1>
+	</chapter>
 </book>
Signature · 1 line
~Randy

Fixing all the above in next version.

Thanks,

Eduardo Valentin

#8 lore raw

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

In reply to Eduardo Valentin
Quoted 30 lines · Eduardo Valentin

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

---
  Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
  1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +13 -1
index f8fb8a2..66efed3 100644
@@ -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>

Documentation/DocBook/thermal.tmpl line 109

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+						<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.

Quoted 21 lines
Documentation/DocBook/thermal.tmpl +21 -0
+						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>

Documentation/DocBook/thermal.tmpl line 140

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+				<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

Documentation/DocBook/thermal.tmpl line 142

Quoted 2 lines
Documentation/DocBook/thermal.tmpl +2 -0
+						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.

Quoted 64 lines
Documentation/DocBook/thermal.tmpl +63 -0
+						</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

Documentation/DocBook/thermal.tmpl line 215

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +9 -0
+						cooling-max-state properties)
+						should be defined in a
+						particular device's binding.
+						</para>
+					</glossdef>
+				</glossentry>
+			</glossary>
+		</sect1>
+	</chapter>
  </book>

Cheers,
Mikko.

#9 lore raw

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

Terve Mikko,

Quoted 35 lines · Mikko Perttunen
Quoted 34 lines · Eduardo Valentin

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

---
  Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
  1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +17 -1
index f8fb8a2..66efed3 100644
@@ -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
Quoted 8 lines

Documentation/DocBook/thermal.tmpl line 109

Quoted 6 lines
Documentation/DocBook/thermal.tmpl +6 -0
+						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.

Quoted 35 lines
Quoted 22 lines
Documentation/DocBook/thermal.tmpl +21 -0
+						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>

Documentation/DocBook/thermal.tmpl line 140

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+				<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

Quoted 5 lines

Documentation/DocBook/thermal.tmpl line 142

Quoted 2 lines
Documentation/DocBook/thermal.tmpl +2 -0
+						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!

Quoted 79 lines
Quoted 65 lines
Documentation/DocBook/thermal.tmpl +63 -0
+						</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

Documentation/DocBook/thermal.tmpl line 215

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +9 -0
+						cooling-max-state properties)
+						should be defined in a
+						particular device's binding.
+						</para>
+					</glossdef>
+				</glossentry>
+			</glossary>
+		</sect1>
+	</chapter>
  </book>

Cheers,
Mikko.

#10 lore raw

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

In reply to Eduardo Valentin

Hi Eduardo,

Quoted 34 lines · Eduardo Valentin

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

---
 Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +17 -1
index f8fb8a2..66efed3 100644
@@ -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

Documentation/DocBook/thermal.tmpl line 113

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+						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

#11 lore raw

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

Quoted 48 lines · Javi Merino

Hi Eduardo,

Quoted 34 lines · Eduardo Valentin

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

---
 Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +17 -1
index f8fb8a2..66efed3 100644
@@ -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

Documentation/DocBook/thermal.tmpl line 113

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+						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>
Quoted 7 lines

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

Quoted 6 lines

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

#12 lore raw

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

Quoted 48 lines · Srinivas Pandruvada
Quoted 47 lines · Javi Merino

Hi Eduardo,

Quoted 44 lines · Eduardo Valentin

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

---
 Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)
Documentation/DocBook/thermal.tmpl +27 -1
index f8fb8a2..66efed3 100644
@@ -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>
Quoted 8 lines
Quoted 8 lines

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.

Quoted 5 lines

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.

Quoted 4 lines

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.

Quoted 13 lines

Thanks,
Srinivas

Quoted 6 lines

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

#13 lore raw

RFC PATCH 3/12 thermal: cpu_cooling: remove duplicate documentation entries

In reply to 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

---
 include/linux/cpu_cooling.h | 13 -------------
 1 file changed, 13 deletions(-)
include/linux/cpu_cooling.h +0 -13
index bd95527..a8d827c 100644
@@ -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);
Signature · 1 line
2.1.3
#14 lore raw

RFC PATCH 4/12 thermal: of-thermal: remove kernel doc warn

In reply to 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.

---
 drivers/thermal/of-thermal.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/thermal/of-thermal.c +1 -1
index d717f3d..b66e3b2 100644
@@ -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.
  */
Signature · 1 line
2.1.3
#15 lore raw

RFC PATCH 5/12 thermal: thermal.h: minor kernel doc fix

In reply to Eduardo Valentin

s/scallbacks/callbacks/g

---
 include/linux/thermal.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/thermal.h +1 -1
index fc52e30..46c16a0 100644
@@ -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.
Signature · 1 line
2.1.3
#16 lore raw

RFC PATCH 6/12 thermal: thermal_core: correct kernel doc wording on thermal_zone_get_temp

In reply to Eduardo Valentin

Fix summary wording on thermal_zone_get_temp kernel doc.

---
 drivers/thermal/thermal_core.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/thermal/thermal_core.c +1 -1
index 87e0b07..846b68a 100644
@@ -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.
  *
Signature · 1 line
2.1.3
#17 lore raw

RFC PATCH 7/12 Documentation: thermal docbook: introduce API reference chapter

In reply to 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.

---
 Documentation/DocBook/thermal.tmpl | 9 +++++++++
 1 file changed, 9 insertions(+)
Documentation/DocBook/thermal.tmpl +9 -0
index 66efed3..d6ebbea 100644
@@ -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>
Signature · 1 line
2.1.3
#18 lore raw

RFC PATCH 8/12 thermal: fair share: fix kernel doc entry

In reply to Eduardo Valentin

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

---
 drivers/thermal/fair_share.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
drivers/thermal/fair_share.c +4 -1
index 6e0a3fb..a15ef0b 100644
@@ -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)
 {
Signature · 1 line
2.1.3
#19 lore raw

RFC PATCH 9/12 thermal: user space: fix kernel doc entry

In reply to Eduardo Valentin

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

---
 drivers/thermal/user_space.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
drivers/thermal/user_space.c +4 -1
index 10adcdd..29c91cb 100644
@@ -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)
 {
Signature · 1 line
2.1.3
#20 lore raw

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

In reply to Eduardo Valentin

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

---
 drivers/thermal/gov_bang_bang.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
drivers/thermal/gov_bang_bang.c +3 -2
index c5dd76b..5154929 100644
@@ -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)
 {
Signature · 1 line
2.1.3
#21 lore raw

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

In reply to 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.

---
 drivers/thermal/step_wise.c | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)
drivers/thermal/step_wise.c +19 -6
index fdd1f52..413ee30 100644
@@ -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)
 {
Signature · 1 line
2.1.3
#22 lore raw

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

In reply to 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.

---
 Documentation/DocBook/thermal.tmpl | 67 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
Documentation/DocBook/thermal.tmpl +67 -0
index d6ebbea..cf1a198 100644
@@ -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.
Signature · 1 line
2.1.3
#23 lore raw

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

Hi Eduardo,

Quoted 52 lines · 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.

---
 Documentation/DocBook/thermal.tmpl | 67 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
Documentation/DocBook/thermal.tmpl +31 -0
index d6ebbea..cf1a198 100644
@@ -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>

Documentation/DocBook/thermal.tmpl line 255

Quoted 10 lines
Documentation/DocBook/thermal.tmpl +10 -0
+				<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

Quoted 37 lines
Documentation/DocBook/thermal.tmpl +26 -0
+!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.
Signature · 6 lines
2.1.3

--
To unsubscribe from this list: send the line "unsubscribe linux-pm" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html