blob: 0ddfaf172b53804414078b860ca4605c453a7970 [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>Create an RTX Project</title>
<title>CMSIS-RTOS: Create an RTX Project</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('using.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">Create an RTX Project </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Example projects using CMSIS-RTOS RTX are available for various development boards. To make use of these examples, you need to install a Device Family Pack in ┬ÁVision and use Pack Installer to open a CMSIS-RTOS Blinky project. If you wish to start a CMSIS-RTOS RTX from scratch, follow these steps:</p>
<ul>
<li>Create a new project and select a device.</li>
<li><p class="startli">In the Manage Run-Time Environment window that opens, select <b>CMSIS::CORE</b> and <b>CMSIS::RTOS (API)::Keil RTX</b>. If the <b>Validation Output</b> requires other components to be present, try to use the <b>Resolve</b> button:</p>
<div class="image">
<img src="manage_rte_output.png" alt="manage_rte_output.png"/>
</div>
</li>
<li><p class="startli">Click <b>OK</b>. In the <b>Project</b> window, you will see the files that have been automatically added to you project, such as <b>RTX_Conf_CM.c</b> and the system and startup files:</p>
<div class="image">
<img src="project_window.png" alt="project_window.png"/>
</div>
</li>
<li><p class="startli">You can add template files to the project by right-clicking on <b>Source Group 1</b> and selecting <b>Add New Item to 'Source Group 1'</b>. In the new window, click on <b>User Code Template</b>. On the right-hand side you will see all available template files for CMSIS-RTOS RTX:</p>
<div class="image">
<img src="add_item.png" alt="add_item.png"/>
</div>
</li>
<li>Finally, <a class="el" href="configure.html">configure</a> RTX to the application's needs using the <b>RTX_Conf_CM.c</b> file.</li>
</ul>
<h1><a class="anchor" id="DefRefObj"></a>
Define and Reference Object Definitions</h1>
<p>With <code>#define</code> <code>osObjectsExternal</code> objects are defined as external symbols. This allows to create a consistent header file that is used throughout a project. If you are using the <b>CMSIS-RTOS</b> <b>'main'</b> <b>function</b> user code template, such a header file (called <code>osObjects.h</code>) will be added automatically to the project:</p>
<p><b>Code</b> <b>Example</b> </p>
<div class="fragment"><div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div>
<div class="line"><span class="comment"> * osObjects.h: CMSIS-RTOS global object definitions for an application</span></div>
<div class="line"><span class="comment"> *----------------------------------------------------------------------------</span></div>
<div class="line"><span class="comment"> </span></div>
<div class="line"><span class="comment"> * This header file defines global RTOS objects used throughout a project</span></div>
<div class="line"><span class="comment"> </span></div>
<div class="line"><span class="comment"> * #define osObjectsPublic indicates that objects are defined; without that</span></div>
<div class="line"><span class="comment"> * definition the objects are defined as external symbols.</span></div>
<div class="line"><span class="comment"> </span></div>
<div class="line"><span class="comment"> *--------------------------------------------------------------------------*/</span></div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#ifndef __osObjects</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define __osObjects</span></div>
<div class="line"><span class="preprocessor"></span> </div>
<div class="line"><span class="preprocessor">#if (!defined (osObjectsPublic))</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define osObjectsExternal // define RTOS objects with extern attribute</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#endif</span></div>
<div class="line"><span class="preprocessor"></span> </div>
<div class="line"><span class="preprocessor">#include &lt;<a class="code" href="cmsis__os_8h.html">cmsis_os.h</a>&gt;</span> <span class="comment">// CMSIS RTOS header file</span></div>
<div class="line"> </div>
<div class="line"><span class="comment">// global &#39;thread&#39; functions -------------------------------------------------</span></div>
<div class="line"><span class="keyword">extern</span> <span class="keywordtype">void</span> thread_sample (<span class="keywordtype">void</span> <span class="keyword">const</span> *argument); <span class="comment">// function prototype</span></div>
<div class="line"><a class="code" href="group__CMSIS__RTOS__ThreadMgmt.html#gaee93d929beb350f16e5cc7fa602e229f">osThreadDef</a> (thread_sample, <a class="code" href="cmsis__os_8h.html#ga7f2b42f1983b9107775ec2a1c69a849aa193b650117c209b4a203954542bcc3e6">osPriorityBelowNormal</a>, 1, 100);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// global &#39;memory pools&#39; -----------------------------------------------------</span></div>
<div class="line"><a class="code" href="group__CMSIS__RTOS__PoolMgmt.html#ga87b471d4fe2d5dbd0040708edd52771b">osPoolDef</a>(MyPool, 10, <span class="keywordtype">long</span>);</div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#endif // __osObjects</span></div>
</div><!-- fragment --><p>This header file defines all objects when included in a C/C++ source file. When <code>#define</code> <code>osObjectsExternal</code> is present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be used throughout the whole project.</p>
<p><b>Code</b> <b>Example</b> </p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;osObjects.h&quot;</span> <span class="comment">// Definition of the CMSIS-RTOS objects</span></div>
</div><!-- fragment --><h1><a class="anchor" id="UsingIRQs"></a>
Using IRQ Interrupts</h1>
<p>The CMSIS-RTOS RTX kernel uses the following interrupts:</p>
<ul>
<li>Timer interrupt (SysTick or alternative peripheral timer) to generate periodic timer ticks</li>
<li>SVC (Supervisor Call) when calling the majority of RTX functions from <b>Thread</b> mode</li>
<li>PendSV (request for system-level service) when calling certain RTX functions from <b>Handler</b> mode</li>
</ul>
<p>Interrupts can be used without limitation. Interrupt priority grouping can be used with some restrictions:</p>
<ul>
<li>IRQ interrupts are never disabled by RTX Kernel for Armv7-M architectures (Cortex-M3/M4/M7).</li>
<li>Software interrupt 0 is used by RTX and cannot be used in an application.</li>
<li>RTX uses its own SVC Handler which is automatically linked from the library. <a class="el" href="svcFunctions.html">SVC Functions</a> explains how to use a custom SVC table.</li>
<li>When interrupt <b>priority</b> <b>grouping</b> is used, the PRIGROUP must be set before the <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga53d078a801022e202e8115c083ece68e">osKernelInitialize()</a> function is called (usually in the SystemInit() function in the system_<em>device</em>.c file). The kernel reads the value of PRIGROUP to correctly set internal interrupt pre-emption priorities.</li>
<li>Allowed values for <b>PRIGROUP</b> are from 0 to 6. The PRIGROUP value 7 will cause RTX to fail.</li>
<li>The lowest two pre-emption priorities are reserved for RTX kernel, all remaining pre-emption priorities are available to be used in an application.</li>
<li>Do not change the priority used by the RTX kernel. If this cannot be avoided, ensure that the preempt priority of SysTick/PendSV is lower than SVC.</li>
<li>Check the <b>main stack size</b> configured from the device startup file if you see sporadic crashes of your application. Supervisor Calls (SVCs) are used when calling RTX functions from Thread mode. All SVC calls use the main stack. </li>
</ul>
</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>