begriffs open source - cmsis/blob - main/RTOS2/html/cre_rtx_proj.html

   1 <!-- HTML header for doxygen 1.9.6-->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   6 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
   7 <meta name="viewport" content="width=device-width, initial-scale=1"/>
   8 <title>CMSIS-RTOS2: Create an RTX5 Project</title>
   9 <link href="doxygen.css" rel="stylesheet" type="text/css"/>
  10 <link href="tabs.css" rel="stylesheet" type="text/css"/>
  11 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  12 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  13 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  14 <script type="text/javascript" src="jquery.js"></script>
  15 <script type="text/javascript" src="dynsections.js"></script>
  16 <script type="text/javascript" src="printComponentTabs.js"></script>
  17 <script type="text/javascript" src="footer.js"></script>
  18 <script type="text/javascript" src="navtree.js"></script>
  19 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  20 <script type="text/javascript" src="resize.js"></script>
  21 <script type="text/javascript" src="navtreedata.js"></script>
  22 <script type="text/javascript" src="navtree.js"></script>
  23 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  24 <script type="text/javascript" src="search/searchdata.js"></script>
  25 <script type="text/javascript" src="search/search.js"></script>
  26 <script type="text/javascript">
  27 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  28   $(document).ready(function() { init_search(); });
  29 /* @license-end */
  30 </script>
  31 <script type="text/javascript" src="darkmode_toggle.js"></script>
  32 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  33 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  34 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  35 <link href="version.css" rel="stylesheet" type="text/css" />
  36 <script type="text/javascript" src="../../version.js"></script>
  37 </head>
  38 <body>
  39 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  40 <div id="titlearea">
  41 <table cellspacing="0" cellpadding="0">
  42  <tbody>
  43  <tr style="height: 55px;">
  44   <td id="projectlogo" style="padding: 1.5em;"><img alt="Logo" src="cmsis_logo_white_small.png"/></td>
  45   <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
  46    <div id="projectname">CMSIS-RTOS2
  47    &#160;<span id="projectnumber"><script type="text/javascript">
  48      <!--
  49      writeHeader.call(this);
  50      writeVersionDropdown.call(this, "CMSIS-RTOS2");
  51      //-->
  52     </script>
  53    </span>
  54    </div>
  55    <div id="projectbrief">Real-Time Operating System: API and RTX Reference Implementation</div>
  56   </td>
  57    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
  58         <span class="left">
  59           <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
  60           <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
  61                onfocus="searchBox.OnSearchFieldFocus(true)"
  62                onblur="searchBox.OnSearchFieldFocus(false)"
  63                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  64           </span><span class="right">
  65             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
  66           </span>
  67         </div>
  68 </td>
  69   <!--END !PROJECT_NAME-->
  70  </tr>
  71  </tbody>
  72 </table>
  73 </div>
  74 <!-- end header part -->
  75 <div id="CMSISnav" class="tabs1">
  76   <ul class="tablist">
  77     <script type="text/javascript">
  78       writeComponentTabs.call(this);
  79     </script>
  80   </ul>
  81 </div>
  82 <!-- Generated by Doxygen 1.9.6 -->
  83 <script type="text/javascript">
  84 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  85 var searchBox = new SearchBox("searchBox", "search/",'.html');
  86 /* @license-end */
  87 </script>
  88 </div><!-- top -->
  89 <div id="side-nav" class="ui-resizable side-nav-resizable">
  90   <div id="nav-tree">
  91     <div id="nav-tree-contents">
  92       <div id="nav-sync" class="sync"></div>
  93     </div>
  94   </div>
  95   <div id="splitbar" style="-moz-user-select:none;"
  96        class="ui-resizable-handle">
  97   </div>
  98 </div>
  99 <script type="text/javascript">
 100 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 101 $(document).ready(function(){initNavTree('cre_rtx_proj.html',''); initResizable(); });
 102 /* @license-end */
 103 </script>
 104 <div id="doc-content">
 105 <!-- window showing the filter options -->
 106 <div id="MSearchSelectWindow"
 107      onmouseover="return searchBox.OnSearchSelectShow()"
 108      onmouseout="return searchBox.OnSearchSelectHide()"
 109      onkeydown="return searchBox.OnSearchSelectKey(event)">
 110 </div>
 111
 112 <!-- iframe showing the search results (closed by default) -->
 113 <div id="MSearchResultsWindow">
 114 <div id="MSearchResults">
 115 <div class="SRPage">
 116 <div id="SRIndex">
 117 <div id="SRResults"></div>
 118 <div class="SRStatus" id="Loading">Loading...</div>
 119 <div class="SRStatus" id="Searching">Searching...</div>
 120 <div class="SRStatus" id="NoMatches">No Matches</div>
 121 </div>
 122 </div>
 123 </div>
 124 </div>
 125
 126 <div><div class="header">
 127   <div class="headertitle"><div class="title">Create an RTX5 Project </div></div>
 128 </div><!--header-->
 129 <div class="contents">
 130 <div class="textblock"><p>The steps to create a microcontroller application using RTX5 are:</p><ul>
 131 <li>Create a new project and select a microcontroller device.</li>
 132 <li>In the Manage Run-Time Environment window, select <b>CMSIS::CORE</b> and <b>CMSIS::RTOS2 (API)::Keil RTX5</b>. You can choose to either add RTX as a library (Variant: <b>Library</b>) or to add the full source code (Variant: <b>Source</b> - required if using the <a href="https://www.keil.com/pack/doc/compiler/EventRecorder/html/index.html" target="_blank"><b>Event Recorder</b></a>):</li>
 133 </ul>
 134 <div class="image">
 135 <img src="manage_rte_output.png" alt=""/>
 136 </div>
 137 <ul>
 138 <li>If the <b>Validation Output</b> requires other components to be present, try to use the <b>Resolve</b> button.</li>
 139 <li>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_Config.h</b>, <b>RTX_Config.c</b>, the library or the source code files, as well as the system and startup files:</li>
 140 </ul>
 141 <div class="image">
 142 <img src="project_window.png" alt=""/>
 143 </div>
 144 <ul>
 145 <li>If using the Variant: <b>Source</b> as stated above, you have to assure to use at least C99 compiler mode (Project Options -&gt; C/C++ -&gt; C99 Mode). <br  />
 146 </li>
 147 <li>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:</li>
 148 </ul>
 149 <div class="image">
 150 <img src="add_item.png" alt=""/>
 151 </div>
 152 <ul>
 153 <li><a class="el" href="config_rtx5.html">Configure</a> RTX5 to the application's needs using the <b>RTX_Config.h</b> file.</li>
 154 </ul>
 155 <h1><a class="anchor" id="cre_rtx_cortexa"></a>
 156 Additional requirements for RTX on Cortex-A</h1>
 157 <p>Cortex-A based microcontrollers are less unified with respect to the interrupt and timer implementations used compared to M-class devices. Thus RTX requires additional components when an A-class device is used, namely <a href="../../Core_A/html/group__irq__ctrl__gr.html"><b>IRQ Controller (API)</b></a> and <a class="el" href="group__CMSIS__RTOS__TickAPI.html">OS Tick (API)</a> implementations.</p>
 158 <div class="image">
 159 <img src="manage_rte_cortex-a.png" alt=""/>
 160 </div>
 161 <p>The default implementations provided along with CMSIS are</p><ul>
 162 <li>Arm <a href="../../Core_A/html/group__GIC__functions.html">Generic Interrupt Controller (GIC)</a></li>
 163 <li>Arm Cortex-A5, Cortex-A9 <a href="../../Core_A/html/group__PTM__timer__functions.html">Private Timer (PTIM)</a></li>
 164 <li>Arm Cortex-A7 <a href="../../Core_A/html/group__PL1__timer__functions.html">Generic Physical Timer (GTIM)</a></li>
 165 </ul>
 166 <p>For devices not implementing GIC, PTIM nor GTIM please refer to the according device family pack and select the proper implementations.</p>
 167 <h1><a class="anchor" id="cre_UsingIRQs"></a>
 168 Using Interrupts on Cortex-M</h1>
 169 <p>On Cortex-M processors, the RTX5 kernel uses the following interrupt exceptions. The table below also lists the priorities that must be assigned to these interrupts.</p>
 170 <table class="markdownTable">
 171 <tr class="markdownTableHead">
 172 <th class="markdownTableHeadLeft">Handler   </th><th class="markdownTableHeadLeft">Priority   </th><th class="markdownTableHeadLeft">Interrupt/Exception    </th></tr>
 173 <tr class="markdownTableRowOdd">
 174 <td class="markdownTableBodyLeft">SysTick   </td><td class="markdownTableBodyLeft">lowest   </td><td class="markdownTableBodyLeft">Kernel system timer interrupt to generate periodic timer ticks    </td></tr>
 175 <tr class="markdownTableRowEven">
 176 <td class="markdownTableBodyLeft">PendSV   </td><td class="markdownTableBodyLeft">lowest   </td><td class="markdownTableBodyLeft">PendSV (request for system-level service) when calling certain RTX functions from <b>Handler</b> mode    </td></tr>
 177 <tr class="markdownTableRowOdd">
 178 <td class="markdownTableBodyLeft">SVC   </td><td class="markdownTableBodyLeft">lowest+1   </td><td class="markdownTableBodyLeft">Supervisor Call used to enter the RTOS kernel from <b>Thread</b> mode   </td></tr>
 179 </table>
 180 <p>Other device interrupts can be used without limitation. For Arm Cortex-M3/M4/M7  /M23/M33/M35P  processors, interrupts are never disabled by RTX Kernel.</p>
 181 <p><b>Usage of interrupt priority grouping</b></p><ul>
 182 <li>The interrupt priority grouping should be configured using the CMSIS-Core function NVIC_SetPriorityGrouping before calling the function <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart()</a>. The RTX kernel uses the priority group value to setup the priority for SysTick and PendSV interrupts.</li>
 183 <li>The RTX kernel sets the priority for the interrupts/exceptions listed in above table and uses the lowest two priority levels.</li>
 184 <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>
 185 <li>Permitted priority group values are 0 to 6. The priority group value 7 will cause RTX to fail as there is only one priority level available.</li>
 186 <li>The <b>main stack</b> is used to run the RTX functionality. It is therefore required to configure sufficient stack for the RTX kernel execution.</li>
 187 </ul>
 188 <p><b>Code Example</b> </p><div class="fragment"><div class="line"><a class="code hl_function" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a>();                            <span class="comment">// initialize RTX</span></div>
 189 <div class="line">NVIC_SetPriorityGrouping (3);                    <span class="comment">// setup priority grouping</span></div>
 190 <div class="line">tread_id = <a class="code hl_function" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a>(tread_func, NULL, NULL);  <span class="comment">// create some threads</span></div>
 191 <div class="line"><a class="code hl_function" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a> ();                                <span class="comment">// start RTX kernel</span></div>
 192 <div class="ttc" id="agroup__CMSIS__RTOS__KernelCtrl_html_ga9ae2cc00f0d89d7b6a307bba942b5221"><div class="ttname"><a href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a></div><div class="ttdeci">osStatus_t osKernelStart(void)</div><div class="ttdoc">Start the RTOS Kernel scheduler.</div></div>
 193 <div class="ttc" id="agroup__CMSIS__RTOS__KernelCtrl_html_gae818f6611d25ba3140bede410a52d659"><div class="ttname"><a href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a></div><div class="ttdeci">osStatus_t osKernelInitialize(void)</div><div class="ttdoc">Initialize the RTOS Kernel.</div></div>
 194 <div class="ttc" id="agroup__CMSIS__RTOS__ThreadMgmt_html_ga48d68b8666d99d28fa646ee1d2182b8f"><div class="ttname"><a href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a></div><div class="ttdeci">osThreadId_t osThreadNew(osThreadFunc_t func, void *argument, const osThreadAttr_t *attr)</div><div class="ttdoc">Create a thread and add it to Active Threads.</div></div>
 195 </div><!-- fragment --><h1><a class="anchor" id="cre_rtx_proj_specifics"></a>
 196 Add support for RTX specific functions</h1>
 197 <p>If you require some of the RTX specific functions in your application code, #include the <a class="el" href="theory_of_operation.html#rtx_os_h">header file rtx_os.h</a>. This enables <a class="el" href="theory_of_operation.html#lowPower">low-power</a> and <a class="el" href="theory_of_operation.html#TickLess">tick-less</a> operation modes.</p>
 198 <h1><a class="anchor" id="cre_rtx_proj_er"></a>
 199 Add Event Recorder Visibility</h1>
 200 <p>RTX5 interfaces to the <a href="https://www.keil.com/pack/doc/compiler/EventRecorder/html/index.html" target="_blank"><b>Event Recorder</b></a> to provide event information which helps you to understand and analyze the operation.</p>
 201 <ul>
 202 <li>To use the Event Recorder together with RTX5, select the software component <b>Compiler:Event Recorder</b>.</li>
 203 <li>Select the <b>Source</b> variant of the software component <b>CMSIS:RTOS2 (API):Keil RTX5</b>.</li>
 204 </ul>
 205 <div class="image">
 206 <img src="event_recorder_rte.png" alt=""/>
 207 <div class="caption">
 208 Component selection for Event Recorder</div></div>
 209 <ul>
 210 <li>Enable the related settings under <a class="el" href="config_rtx5.html#evtrecConfig">Event Recorder Configuration</a>.</li>
 211 <li>Build the application code and download it to the debug hardware.  Once the target application generates event information, it can be viewed in the µVision debugger using the <b>Event</b> <b>Recorder</b>. </li>
 212 </ul>
 213 </div></div><!-- contents -->
 214 </div><!-- PageDoc -->
 215 </div><!-- doc-content -->
 216 <!-- start footer part -->
 217 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 218   <ul>
 219     <li class="footer">
 220       <script type="text/javascript">
 221         <!--
 222         writeFooter.call(this);
 223         //-->
 224       </script>
 225     </li>
 226   </ul>
 227 </div>
 228 </body>
 229 </html>