blob: a04fc4da43378bbad0700eb151b531f0dbc52ba4 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>Theory of Operation</title>
<title>CMSIS-RTOS: Theory of Operation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="cmsis.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="printComponentTabs.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 46px;">
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">CMSIS-RTOS
&#160;<span id="projectnumber">Version 1.03</span>
</div>
<div id="projectbrief">Real-Time Operating System: API and RTX Reference Implementation.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<div id="CMSISnav" class="tabs1">
<ul class="tablist">
<script type="text/javascript">
<!--
writeComponentTabs.call(this);
//-->
</script>
</ul>
</div>
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main&#160;Page</span></a></li>
<li class="current"><a href="pages.html"><span>Usage&#160;and&#160;Description</span></a></li>
<li><a href="modules.html"><span>Reference</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('theory.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Theory of Operation </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This section describes how CMSIS-RTOS RTX manages the resources of the target system. Many aspects of the CMSIS-RTOS RTX kernel can be configured. Information about configuration options is mentioned where applicable.</p>
<h1><a class="anchor" id="osFeature"></a>
Settings for osFeature_xxx in cmsis_os.h</h1>
<p>CMSIS-RTOS RTX uses the following #defines.</p>
<table class="doxtable">
<tr>
<th>osFeature_xxx #define </th><th>RTX Setting </th><th>Meaning </th></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga22f7d235bc9f783933bd5a981fd79696">osFeature_MainThread</a> </td><td>1 </td><td>main can be a thread </td></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gadd84b683001de327894851b428587caa">osFeature_Pool</a> </td><td>1 </td><td>Memory Pools are available </td></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__Mail.html#gaceb2e0071ce160d153047f2eac1aca8e">osFeature_MailQ</a> </td><td>1 </td><td>Mail Queues are available </td></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__Message.html#ga479a6561f859e3d4818e25708593d203">osFeature_MessageQ</a> </td><td>1 </td><td>Message Queues are available </td></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__SignalMgmt.html#ga01edde265710d883b6e237d34a6ef4a6">osFeature_Signals</a> </td><td>16 </td><td>16 Signal Flags are available per thread </td></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga7da4c7bfb340779c9fc7b321f5ab3e3a">osFeature_Semaphore</a> </td><td>65535 </td><td>Maximum count for <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga97381e8e55cd47cec390bf57c96d6edb">osSemaphoreCreate</a> function </td></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__Wait.html#ga6c97d38879ae86491628f6e647639bad">osFeature_Wait</a> </td><td>0 </td><td><a class="el" href="technicalData.html#osWait">osWait</a> is not available </td></tr>
<tr>
<td><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae554ec16c23c5b7d65affade2a351891">osFeature_SysTick</a> </td><td>1 </td><td><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gad0262e4688e95d1e9038afd9bcc16001">osKernelSysTick</a> functions are available </td></tr>
</table>
<h1><a class="anchor" id="KernelTimer"></a>
RTX Kernel Timer Tick and Thread Management</h1>
<p>By default, CMSIS-RTOS RTX uses the Cortex-M <a href="http://www.keil.com/support/man/docs/gsac/GSAC_SYSTICKtimer.htm" target="_blank">SysTick</a> timer to generate periodic interrupts for the RTX kernel timer tick. CMSIS-RTOS provides <a class="el" href="group__CMSIS__RTOS__TimerMgmt.html">Timer Management</a> functions and several CMSIS-RTOS functions have a timeout parameter. This periodic RTX kernel timer tick interrupt is used to derive the required time interval. CMSIS-RTOS RTX also provides configuration options for a alternative timer and tick-less operation. Refer to <a class="el" href="timerTick.html">RTX Kernel Tick Timer Configuration</a> for more information.</p>
<p>To handle timeout and time delays for threads, the CMSIS-RTOS RTX thread management is controlled by the RTX kernel timer tick interrupt. The thread context switch itself is implemented in the HAL_CMx.x hardware abstraction layer source files. The thread context contains all CPU registers (R0 - R12), the return address (LR), the program counter (PC), and the processor status register (xPSR). For the Cortex-M4 FPU and Cortex-M7 FPU the floating point status and registers (S0 - S32, FPSCR) are also part of the thread context.</p>
<p>When a thread switch occurs:</p>
<ul>
<li>the thread context of the current running thread is stored on the local stack of this thread.</li>
<li>the stack pointer is switched to the next running thread.</li>
<li>the thread context of this next running thread is restored and this thread starts to run.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd><ul>
<li>For Cortex-M0, Cortex-M3, Cortex-M4, and Cortex-M7 the thread context requires 64 bytes on the local stack.</li>
<li>For Cortex-M4 FPU and Cortex-M7 FPU the thread context requires 200 bytes on the local stack. For devices with Cortex-M4 FPU and Cortex-M7 FPU the default stack space should be increased to a minimum of 300 bytes.</li>
</ul>
</dd></dl>
<p>Each thread is provided with an separate stack that holds the thread context and stack space for automatic variables and return addresses for function call nesting. The stack sizes of the RTX threads are flexible configurable as explained in the section <a class="el" href="threadConfig.html">Thread Configuration</a>. RTX even offers a configurable checking for stack overflows. Refer to <a class="el" href="threadConfig.html#stackCheck">Stack Overflow Checking</a> for more information.</p>
<h1><a class="anchor" id="RTX_Threads"></a>
CMSIS-RTOS RTX Threads</h1>
<p>At startup time, the CMSIS-RTOS RTX creates the following threads:</p>
<ul>
<li><b>main</b> : the 'main' function of the application code is started as thread with the <a class="el" href="cmsis__os_8h.html#ga7f2b42f1983b9107775ec2a1c69a849aa45a2895ad30c79fb97de18cac7cc19f1">osPriorityNormal</a>.</li>
<li><b>os_idle_demon</b> : this thread executes when no other thread is in <b>RUNNING</b> state. The code of that thread is provided in the <a class="el" href="dirstructfiles.html#RTX_Conf_CM">RTX_Conf_CM.c</a> file and is typically used to put the system into a power-saving mode.</li>
<li><b>osTimerThread</b> : this thread executes the <a class="el" href="group__CMSIS__RTOS__TimerMgmt.html">Timer Management</a> callback functions. This thread can be disabled; refer to <a class="el" href="systemConfig.html#UserTimer">User Timer Management</a> for configuration options.</li>
</ul>
<h1><a class="anchor" id="PriorityInversion"></a>
Priority Inversion on Resource Sharing</h1>
<p>The CMSIS-RTOS RTX employs a priority-based preemptive scheduler which ensures that from all the threads that are in the <b>READY</b> state, the thread with the highest priority gets executed and becomes the <b>RUNNING</b> thread. Because threads share resources, events that are outside of the control of the RTX scheduler can prevent the highest priority thread from running when it should. If this happens, a critical deadline could be missed, causing the system to fail. Priority inversion is the term of a scenario in which the highest-priority ready task fails to run when it should.</p>
<p>Threads typically share resources to communicate and process data by using the CMSIS-RTOS <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html">Mutexes</a>. At any time, two or more threads share a resource, such as a memory buffer or a serial port, one of them may have a higher priority. It is expected that the higher-priority thread runs as soon as it is in the <b>READY</b> state. However, if the lower-priority thread is using a shared resource of a higher-priority thread, this higher-priority thread must wait until the lower-priority thread releases the shared resource.</p>
<p>To prevent priority inversions, the CMSIS-RTOS RTX implements a <b>priority inheritance</b> method for the <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html">Mutexes</a>. A lower-priority thread inherit the priority of any higher-priority thread that is waiting with <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga5e1752b73f573ee015dbd9ef1edaba13">osMutexWait</a> on a shared resource. During the time the higher-priority thread is in <b>WAITING</b> state, the lower-priority thread runs at the same priority of a higher-priority pending thread. When the lower-priority thread stops to share a resource with <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga006e4744d741e8e132c3d5bbc295afe1">osMutexRelease</a>, the original priority is assigned to this thread again.</p>
<h1><a class="anchor" id="isr_function_calls"></a>
Function calls from Interrupt Service Routines (ISR)</h1>
<p>The following CMSIS-RTOS functions can be called from threads <em>and</em> Interrupt Service Routines (ISR):</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga3b571de44cd3094c643247a7397f86b5">osKernelRunning</a></li>
<li><a class="el" href="group__CMSIS__RTOS__SignalMgmt.html#ga3de2730654589d6c3559c4b9e2825553">osSignalSet</a></li>
<li><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#gab108914997c49e14d8ff1ae0d1988ca0">osSemaphoreRelease</a></li>
<li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gaa0b2994f1a866c19e0d11e6e0d44f543">osPoolAlloc</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga9f129fcad4730fbd1048ad4fa262f36a">osPoolCAlloc</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga4a861e9c469c9d0daf5721bf174f8e54">osPoolFree</a></li>
<li><a class="el" href="group__CMSIS__RTOS__Message.html#gac0dcf462fc92de8ffaba6cc004514a6d">osMessagePut</a>, <a class="el" href="group__CMSIS__RTOS__Message.html#ga6c6892b8f2296cca6becd57ca2d7e1ae">osMessageGet</a></li>
<li><a class="el" href="group__CMSIS__RTOS__Mail.html#gadf5ce811bd6a56e617e902a1db6c2194">osMailAlloc</a>, <a class="el" href="group__CMSIS__RTOS__Mail.html#ga8fde74f6fe5b9e88f75cc5eb8f2124fd">osMailCAlloc</a>, <a class="el" href="group__CMSIS__RTOS__Mail.html#gac6ad7e6e7d6c4a80e60da22c57a42ccd">osMailGet</a>, <a class="el" href="group__CMSIS__RTOS__Mail.html#ga485ef6f81854ebda8ffbce4832181e02">osMailPut</a>, <a class="el" href="group__CMSIS__RTOS__Mail.html#ga27c1060cf21393f96b4fd1ed1c0167cc">osMailFree</a></li>
</ul>
<p>Functions that cannot be called from an ISR are verifying the interrupt status and return the status code <b>osErrorISR</b> in case that they are called from an ISR context. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="rtxImplementation.html">RTX Implementation</a></li>
<li class="footer">Generated on Wed Jul 10 2019 15:21:02 for CMSIS-RTOS Version 1.03 by Arm Ltd. All rights reserved.
<!--
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
-->
</li>
</ul>
</div>
</body>
</html>