Google Git
Sign in
apache / nuttx-website / refs/heads/asf-site / . / content / docs / 12.7.0 / components / drivers / thermal / index.html
blob: 92f3bcedb7625e9c2d8a1b1abdb70fa9e7928dfe [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Thermal Framework &mdash; NuttX latest documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/css/theme.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css" />
<link rel="shortcut icon" href="../../../_static/favicon.ico"/>
<script src="../../../_static/jquery.js"></script>
<script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
<script src="../../../_static/doctools.js"></script>
<script src="../../../_static/sphinx_highlight.js"></script>
<script src="../../../_static/clipboard.min.js"></script>
<script src="../../../_static/copybutton.js"></script>
<script src="../../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="NXFLAT" href="../../nxflat.html" />
<link rel="prev" title="Wireless Drivers" href="../special/wireless.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../../index.html" class="icon icon-home"> NuttX
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select onchange="javascript:location.href = this.value;">
<option value="../../../../latest" selected="selected">latest</option>
<option value="../../../../10.0.0" >10.0.0</option>
<option value="../../../../10.0.1" >10.0.1</option>
<option value="../../../../10.1.0" >10.1.0</option>
<option value="../../../../10.2.0" >10.2.0</option>
<option value="../../../../10.3.0" >10.3.0</option>
<option value="../../../../11.0.0" >11.0.0</option>
<option value="../../../../12.0.0" >12.0.0</option>
<option value="../../../../12.1.0" >12.1.0</option>
<option value="../../../../12.2.0" >12.2.0</option>
<option value="../../../../12.2.1" >12.2.1</option>
<option value="../../../../12.3.0" >12.3.0</option>
<option value="../../../../12.4.0" >12.4.0</option>
<option value="../../../../12.5.0" >12.5.0</option>
<option value="../../../../12.5.1" >12.5.1</option>
<option value="../../../../12.6.0" >12.6.0</option>
<option value="../../../../12.7.0" >12.7.0</option>
<option value="../../../../12.8.0" >12.8.0</option>
<option value="../../../../12.9.0" >12.9.0</option>
<option value="../../../../12.10.0" >12.10.0</option>
<option value="../../../../12.11.0" >12.11.0</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../platforms/index.html">Supported Platforms</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">OS Components</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../binfmt.html">Binary Loader</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Device Drivers</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../character/index.html">Character Device Drivers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../block/index.html">Block Device Drivers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../special/index.html">Specialized Device Drivers</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Thermal Framework</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#brief">Brief</a></li>
<li class="toctree-l4"><a class="reference internal" href="#device-driver">Device Driver</a></li>
<li class="toctree-l4"><a class="reference internal" href="#board-customization">Board Customization</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#lower-half-and-upper-half">Lower-half and upper-half</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#subdirectories-of-nuttx-drivers">Subdirectories of <code class="docutils literal notranslate"><span class="pre">nuttx/drivers</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#skeleton-files">Skeleton Files</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#drivers-early-initialization">Drivers Early Initialization</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../nxflat.html">NXFLAT</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nxgraphics/index.html">NX Graphics Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../paging.html">On-Demand Paging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../audio/index.html">Audio Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../filesystem/index.html">NuttX File System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../libs/index.html">NuttX libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../net/index.html">Network Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../mm/index.html">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../syscall.html">Syscall Layer</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../tools/index.html"><code class="docutils literal notranslate"><span class="pre">/tools</span></code> Host Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../arch/index.html">Architecture-Specific Code</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../boards.html">Boards Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../cmake.html">CMake Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../openamp.html">OpenAMP Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../video.html">Video Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../crypto.html">Crypto API Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../wireless.html">Wireless Subsystem</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../implementation/index.html">Implementation Details</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../logos/index.html">NuttX Logos</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../index.html">OS Components</a></li>
<li class="breadcrumb-item"><a href="../index.html">Device Drivers</a></li>
<li class="breadcrumb-item active">Thermal Framework</li>
<li class="wy-breadcrumbs-aside">
<a href="../../../_sources/components/drivers/thermal/index.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="thermal-framework">
<h1>Thermal Framework<a class="headerlink" href="#thermal-framework" title="Permalink to this heading"></a></h1>
<p>Thermal Framework is a subsystem in the kernel that provides interfaces for thermal management of devices. It is designed to monitor the temperature of various components and adjust their operating conditions to prevent overheating. The framework is responsible for controlling the cooling devices, such as fans and heatsinks, to maintain the temperature within safe limits. It provides a unified thermal management interface that can be used by different thermal drivers. The drivers can be implemented by hardware vendors to support their specific thermal management requirements.</p>
<section id="brief">
<h2>Brief<a class="headerlink" href="#brief" title="Permalink to this heading"></a></h2>
<ol class="arabic simple">
<li><dl class="simple">
<dt>Support Zone, Cooling Device and Governor</dt><dd><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">Zone</span></code>: Responsible for monitoring the temperature of the specified area, obtains the temperature through the temperature sensor, and the sensor driver returns the temperature through callback function.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Cooling</span> <span class="pre">Device</span></code>: A cooling device is a device that can reduce the temperature by using resources such as cpufreq, fan, etc. The cpufreq cooling device driver is preset to simplify CPU frequency modulation temperature control.</p></li>
<li><dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">Governor</span></code>: For temperature control, you can use the preset or custom registered one, preset “step_wise” governor:</dt><dd><ul>
<li><p>When the temperature of the “Zone” reaches the temperature trip point, and the temperature change trend rises or stabilizes (“step_wise” obtains the value of the corresponding “Zone” every 20ms [<code class="docutils literal notranslate"><span class="pre">CONFIG_THERMAL_DUMMY_POLLING_DELAY=200</span></code>, <code class="docutils literal notranslate"><span class="pre">CONFIG_USEC_PER_TICK=100</span></code>]), the current temperature equals to OR greater than the last obtained temperature value), improve the state of the “Cooling Device” (trigger the cooling operation executed by the corresponding state, Through <code class="docutils literal notranslate"><span class="pre">set_state</span></code>).</p></li>
<li><p>When the temperature of the zone is lower than the temperature trip point, and the temperature trend is steadily decreasing, the state of the “Cooling Device” is reduced.</p></li>
</ul>
</dd>
</dl>
</li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Support three types of temperatures trip points: <code class="docutils literal notranslate"><span class="pre">THERMAL_NORMAL</span></code>, <code class="docutils literal notranslate"><span class="pre">THERMAL_HOT</span></code> and <code class="docutils literal notranslate"><span class="pre">THERMAL_CRITICAL</span></code></dt><dd><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">NORMAL</span></code>: When the device temperature reaches temperature of this trip point, control needs to be started. If current temperature equals to the temperature obtained last time, the temperature control level(“cooling state”) is maintained. When it is greater than, “cooling state” increased.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">HOT</span></code>: When the device temperature reaches this trip point, stricter temperature control (such as resource limiting) is required. If the current temperature is equals to OR greater than temperature obtained last time, the temperature control level is increased.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CRITICAL</span></code>: Shut down / restart the device.</p></li>
</ul>
</dd>
</dl>
</li>
<li><p>ProcFS node supported, used for debugging, and we can get the binding info between “Zone”, “Cooling Decice”, “Trip” and “Governor”, temperature value and cooling state; (for example, “Zone Device”(temperature sensor): <code class="docutils literal notranslate"><span class="pre">/proc/thermal/cpu_thermal</span></code>), and write 0 or 1 to turn off or on the “Zone Device”;</p></li>
</ol>
</section>
<section id="device-driver">
<h2>Device Driver<a class="headerlink" href="#device-driver" title="Permalink to this heading"></a></h2>
<ol class="arabic">
<li><dl>
<dt>Cooling Device</dt><dd><p>Device providers should provide <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">thermal_cooling_device_ops_s</span></code> instance and private data (optional, for example, <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">dummy_cooling_device_s</span></code>). Please ref to drivers/thermal/thermal_dummy.c:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>static const struct thermal_cooling_device_ops_s g_dummy_fan0_ops =
{
.set_state = dummy_cdev_set_state,
.get_state = dummy_cdev_get_state,
.get_max_state = dummy_cdev_get_max_state,
};
static struct dummy_cooling_device_s g_dummy_fan0_data =
{
.cur_state = 0,
.max_state = 16,
};
int thermal_dummy_init(void)
{
FAR struct thermal_cooling_device_s *cdev;
FAR struct thermal_zone_device_s *zdev;
...
/* Cooling Device */
cdev = thermal_cooling_device_register(&quot;fan0&quot;, &amp;g_dummy_fan0_data,
&amp;g_dummy_fan0_ops);
...
}
</pre></div>
</div>
</dd>
</dl>
</li>
<li><dl>
<dt>Zone Device</dt><dd><dl class="simple">
<dt>The following instances need to be defined:</dt><dd><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">thermal_zone_device_ops_s</span></code>: Get temperature, set temperature window(optional)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">thermal_zone_params_s</span></code>: Describe zone, governor and cooling-maps</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">dummy_zone_device_s</span></code> (private, optional): For temperature and trends</p></li>
</ul>
</dd>
</dl>
<p>For example, drivers/thermal/thermal_dummy.c:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/* Zone Device */
zdev = thermal_zone_device_register(&quot;cpu-thermal&quot;, &amp;g_dummy_zone,
&amp;g_dummy_zone_ops, &amp;g_dummy_params);
static const struct thermal_zone_device_ops_s g_dummy_zone_ops =
{
.get_temp = dummy_zdev_get_temp,
.set_trips = dummy_zdev_set_trips,
};
static struct dummy_zone_device_s g_dummy_zone =
{
.temperature = 45,
.raising = true,
};
</pre></div>
</div>
</dd>
</dl>
</li>
<li><dl>
<dt>Testing / Debuging</dt><dd><ul>
<li><p>Disable Zone Device: <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">0</span> <span class="pre">&gt;</span> <span class="pre">/proc/thermal/cpu-thermal</span></code></p></li>
<li><p>Get binding info:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>nsh&gt; cat /proc/thermal/cpu-thermal
z:cpu-thermal t:77 t:1 h:16 l:0 c:fan0 s:7|7
z:cpu-thermal t:77 t:1 h:3 l:3 c:cpufreq s:3|3
z:cpu-thermal t:77 t:2 h:2 l:0 c:cpufreq s:3|2
</pre></div>
</div>
</li>
</ul>
</dd>
</dl>
</li>
</ol>
</section>
<section id="board-customization">
<h2>Board Customization<a class="headerlink" href="#board-customization" title="Permalink to this heading"></a></h2>
<p>The binding relationship between Trip, Cooling Device, Governor and Zone is shown in thermal_dummy.c. It is expected that the vendor adapter will provide the hardware related initial under <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_BOARD_CUSTOM_DIR</span></code> for product customization, as described in the following comments and structures:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/* thermal-zones {
* &quot;cpu-thermal&quot; {
* polling-delay : CONFIG_THERMAL_DUMMY_POLLING_DELAY;
* passive-delay : CONFIG_THERMAL_DUMMY_PASSIVE_DELAY;
* governor : &quot;step_wise&quot;;
*
* trips {
* &quot;cpu_crit&quot; { 90, 10, THERMAL_CRITICAL };
* &quot;cpu_alert1&quot; { 70, 10, THERMAL_HOT };
* &quot;cpu_alert0&quot; { 60, 10, THERMAL_NORMAL };
* };
*
* cooling-maps {
* &quot;cpu_alert0&quot; {
* { &quot;cpu0&quot;, THERMAL_NO_LIMIT, 3 };
* };
* &quot;cpu_alert1&quot; {
* { &quot;cpu0&quot;, THERMAL_NO_LIMIT, 3 };
* { &quot;fan0&quot;, THERMAL_NO_LIMIT, THERMAL_NO_LIMIT };
* };
* &quot;cpu_crit&quot; {
* { NULL, THERMAL_NO_LIMIT, THERMAL_NO_LIMIT };
* };
* };
* };
* };
*/
static const struct thermal_zone_trip_s g_dummy_trips[] =
{
{.name = &quot;cpu_crit&quot;, .temp = 90, .hyst = 10, .type = THERMAL_CRITICAL},
{.name = &quot;cpu_alert1&quot;, .temp = 70, .hyst = 10, .type = THERMAL_NORMAL},
{.name = &quot;cpu_alert0&quot;, .temp = 60, .hyst = 10, .type = THERMAL_NORMAL},
};
static const struct thermal_zone_map_s g_dummy_maps[] =
{
{
.trip_name = &quot;cpu_alert1&quot;,
.cdev_name = &quot;cpufreq&quot;,
.low = 3,
.high = THERMAL_NO_LIMIT,
.weight = 20
},
{
.trip_name = &quot;cpu_alert1&quot;,
.cdev_name = &quot;fan0&quot;,
.low = THERMAL_NO_LIMIT,
.high = THERMAL_NO_LIMIT,
.weight = 20
},
{
.trip_name = &quot;cpu_alert0&quot;,
.cdev_name = &quot;cpufreq&quot;,
.low = THERMAL_NO_LIMIT,
.high = 2,
.weight = 20
},
};
static const struct thermal_zone_params_s g_dummy_params =
{
.gov_name = &quot;step_wise&quot;,
.polling_delay = CONFIG_THERMAL_DUMMY_POLLING_DELAY,
.trips = g_dummy_trips,
.num_trips = nitems(g_dummy_trips),
.maps = g_dummy_maps,
.num_maps = nitems(g_dummy_maps),
};
</pre></div>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../special/wireless.html" class="btn btn-neutral float-left" title="Wireless Drivers" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../../nxflat.html" class="btn btn-neutral float-right" title="NXFLAT" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2023, The Apache Software Foundation.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>