From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S933803AbbBJAhv (ORCPT <rfc822;w@1wt.eu>);
	Mon, 9 Feb 2015 19:37:51 -0500
Received: from mail-pd0-f172.google.com ([209.85.192.172]:38234 "EHLO
	mail-pd0-f172.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
	with ESMTP id S932686AbbBJAhr (ORCPT
	<rfc822;linux-kernel@vger.kernel.org>);
	Mon, 9 Feb 2015 19:37:47 -0500
From: Eduardo Valentin <edubezval@gmail.com>
To: Rui Zhang <rui.zhang@intel.com>, ezequiel.garcia@free-electrons.com,
        amit.kachhap@linaro.org, viresh.kumar@linaro.org,
        amit.daniel@samsung.com, hongbo.zhang@linaro.com, andrew@lunn.ch,
        durgadoss.r@intel.com, peter@piie.net, shawn.guo@linaro.org,
        aaron.lu@intel.com, caesar.wang@rock-chips.com,
        b.zolnierkie@samsung.com, l.majewski@samsung.com,
        vincenzo.frascino@st.com, mperttunen@nvidia.com,
        mikko.perttunen@kapsi.fi, srinivas.pandruvada@linux.intel.com,
        jacob.jun.pan@linux.intel.com, bcousson@baylibre.com
Cc: LKML <linux-kernel@vger.kernel.org>, Linux PM <linux-pm@vger.kernel.org>,
        Eduardo Valentin <edubezval@gmail.com>
Subject: [PATCH RFC 01/12] Documentation: Introduce Linux Kernel Thermal Framework DocBook
Date: Mon,  9 Feb 2015 17:34:02 -0400
Message-Id: <1423517653-11359-2-git-send-email-edubezval@gmail.com>
X-Mailer: git-send-email 2.1.3
In-Reply-To: <1423517653-11359-1-git-send-email-edubezval@gmail.com>
References: <1423517653-11359-1-git-send-email-edubezval@gmail.com>
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

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