begriffs open source - cmsis/blob - main/RTOS2/html/genRTOS2IF.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: Generic RTOS Interface</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</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 <script type="text/javascript">
  83   writeSubComponentTabs.call(this);
  84 </script>
  85 <!-- Generated by Doxygen 1.9.6 -->
  86 <script type="text/javascript">
  87 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  88 var searchBox = new SearchBox("searchBox", "search/",'.html');
  89 /* @license-end */
  90 </script>
  91 </div><!-- top -->
  92 <div id="side-nav" class="ui-resizable side-nav-resizable">
  93   <div id="nav-tree">
  94     <div id="nav-tree-contents">
  95       <div id="nav-sync" class="sync"></div>
  96     </div>
  97   </div>
  98   <div id="splitbar" style="-moz-user-select:none;"
  99        class="ui-resizable-handle">
 100   </div>
 101 </div>
 102 <script type="text/javascript">
 103 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 104 $(document).ready(function(){initNavTree('genRTOS2IF.html',''); initResizable(); });
 105 /* @license-end */
 106 </script>
 107 <div id="doc-content">
 108 <!-- window showing the filter options -->
 109 <div id="MSearchSelectWindow"
 110      onmouseover="return searchBox.OnSearchSelectShow()"
 111      onmouseout="return searchBox.OnSearchSelectHide()"
 112      onkeydown="return searchBox.OnSearchSelectKey(event)">
 113 </div>
 114
 115 <!-- iframe showing the search results (closed by default) -->
 116 <div id="MSearchResultsWindow">
 117 <div id="MSearchResults">
 118 <div class="SRPage">
 119 <div id="SRIndex">
 120 <div id="SRResults"></div>
 121 <div class="SRStatus" id="Loading">Loading...</div>
 122 <div class="SRStatus" id="Searching">Searching...</div>
 123 <div class="SRStatus" id="NoMatches">No Matches</div>
 124 </div>
 125 </div>
 126 </div>
 127 </div>
 128
 129 <div><div class="header">
 130   <div class="headertitle"><div class="title">Generic RTOS Interface </div></div>
 131 </div><!--header-->
 132 <div class="contents">
 133 <div class="textblock"><p>CMSIS-RTOS2 is a generic API that is agnostic of the underlying RTOS kernel. Application programmers call CMSIS-RTOS2 API functions in the user code to ensure maximum portability from one RTOS to another. Middleware using CMSIS-RTOS2 API takes advantages of this approach by avoiding unnecessary porting efforts.</p>
 134 <div class="image">
 135 <img src="API_Structure.png" alt=""/>
 136 <div class="caption">
 137 CMSIS-RTOS API Structure</div></div>
 138 <p>A typical CMSIS-RTOS2 API implementation interfaces to an existing real-time kernel. The CMSIS-RTOS2 API provides the following attributes and functionalities:</p><ul>
 139 <li>Function names, identifiers, and parameters are descriptive and easy to understand. The functions are powerful and flexible which reduces the number of functions exposed to the user.</li>
 140 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html">Thread Management</a> allows you to define, create, and control threads.</li>
 141 <li>Interrupt Service Routines (ISR) can call some CMSIS-RTOS functions. When a CMSIS-RTOS function cannot be called from an ISR context, it rejects the invocation and returns an error code.</li>
 142 <li>Three different event types support communication between multiple threads and/or ISR:<ul>
 143 <li><a class="el" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html">Thread Flags</a>: may be used to indicate specific conditions to a thread.</li>
 144 <li><a class="el" href="group__CMSIS__RTOS__EventFlags.html">Event Flags</a>: may be used to indicate events to a thread or ISR.</li>
 145 <li><a class="el" href="group__CMSIS__RTOS__Message.html">Messages</a>: can be sent to a thread or an ISR. Messages are buffered in a queue.</li>
 146 </ul>
 147 </li>
 148 <li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html">Mutex Management</a> and <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html">Semaphores</a> are incorporated.</li>
 149 <li>CPU time can be scheduled with the following functionalities:<ul>
 150 <li>A <em>timeout</em> parameter is incorporated in many CMSIS-RTOS functions to avoid system lockup. When a timeout is specified, the system waits until a resource is available or an event occurs. While waiting, other threads are scheduled.</li>
 151 <li>The <a class="el" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e">osDelay</a> and <a class="el" href="group__CMSIS__RTOS__Wait.html#ga3c807924c2d6d43bc2ffb49da3f7f3a1">osDelayUntil</a> functions put a thread into the <b>WAITING</b> state for a specified period of time.</li>
 152 <li>The <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gad01c7ec26535b1de6b018bb9466720e2">osThreadYield</a> provides co-operative thread switching and passes execution to another thread of the same priority.</li>
 153 </ul>
 154 </li>
 155 <li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html">Timer Management</a> functions are used to trigger the execution of functions.</li>
 156 </ul>
 157 <p>The CMSIS-RTOS2 API is designed to optionally incorporate multi-processor systems and/or access protection via the Cortex-M Memory Protection Unit (MPU).</p>
 158 <p>In some RTOS implementations threads may execute on different processors, thus <b>message</b> queues may reside in shared memory resources.</p>
 159 <p>The CMSIS-RTOS2 API encourages the software industry to evolve existing RTOS implementations. RTOS implementations can be different and optimized in various aspects towards the Cortex-M processors. Optional features may be for example</p><ul>
 160 <li>Support of the Cortex-M Memory Protection Unit (MPU).</li>
 161 <li>Support of multi-processor systems.</li>
 162 <li>Support of a DMA controller.</li>
 163 <li>Deterministic context switching.</li>
 164 <li>Round-robin context switching.</li>
 165 <li>Deadlock avoidance, for example with priority inversion.</li>
 166 <li>Zero interrupt latency by using Armv7-M instructions LDREX and STREX.</li>
 167 </ul>
 168 <h1><a class="anchor" id="cmsis_os2_h"></a>
 169 cmsis_os2.h header file</h1>
 170 <p>The file <b>cmsis_os2.h</b> is a standard header file that interfaces to every CMSIS-RTOS2 compliant real-time operating systems (RTOS). Each implementation is provided the same <b><a class="el" href="cmsis__os2_8h.html">cmsis_os2.h</a></b> which defines the interface to the <a class="el" href="rtos_api2.html">CMSIS-RTOS C API v2</a>.</p>
 171 <p>Using the <b><a class="el" href="cmsis__os2_8h.html">cmsis_os2.h</a></b> along with dynamic object allocation allows to create source code or libraries that require no modifications when using on a different CMSIS-RTOS2 implementation.</p>
 172 <h1><a class="anchor" id="usingOS2"></a>
 173 Using a CMSIS-RTOS2 Implementation</h1>
 174 <p>A CMSIS-RTOS2 component may be provided as library or source code (the picture below shows a library). A CMSIS-based application is extended with RTOS functionality by adding a CMSIS-RTOS2 component (and typically some configuration files). The <a class="el" href="genRTOS2IF.html#cmsis_os2_h">cmsis_os2.h header file</a> gives access to RTOS API functions and is the only interface header required when dynamic object allocation is used. This enables portable application that works with every RTOS kernel event without re-compilation of the source code when the kernel is changed.</p>
 175 <p>Static object allocation requires access to RTOS object control block definitions. An implementation specific header file (<em>rtos</em>.h in the picture below) provides access to such definitions.</p>
 176 <div class="image">
 177 <img src="CMSIS_RTOS_Files.png" alt=""/>
 178 <div class="caption">
 179 CMSIS-RTOS File Structure</div></div>
 180 <p>Once the files are added to a project, the user can start working with the CMSIS-RTOS functions. A code example is provided below:</p>
 181 <p><b>Code Example</b> </p><div class="fragment"><div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div>
 182 <div class="line"><span class="comment"> * CMSIS-RTOS &#39;main&#39; function template</span></div>
 183 <div class="line"><span class="comment"> *---------------------------------------------------------------------------*/</span></div>
 184 <div class="line"> </div>
 185 <div class="line"><span class="preprocessor">#include &quot;RTE_Components.h&quot;</span></div>
 186 <div class="line"><span class="preprocessor">#include  CMSIS_device_header</span></div>
 187 <div class="line"><span class="preprocessor">#include &quot;<a class="code" href="cmsis__os2_8h.html">cmsis_os2.h</a>&quot;</span></div>
 188 <div class="line"> </div>
 189 <div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div>
 190 <div class="line"><span class="comment"> * Application main thread</span></div>
 191 <div class="line"><span class="comment"> *---------------------------------------------------------------------------*/</span></div>
 192 <div class="line"><span class="keywordtype">void</span> app_main (<span class="keywordtype">void</span> *argument) {</div>
 193 <div class="line"> </div>
 194 <div class="line">  <span class="comment">// ...</span></div>
 195 <div class="line">  <span class="keywordflow">for</span> (;;) {}</div>
 196 <div class="line">}</div>
 197 <div class="line"> </div>
 198 <div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
 199 <div class="line"> </div>
 200 <div class="line">  <span class="comment">// System Initialization</span></div>
 201 <div class="line">  SystemCoreClockUpdate();</div>
 202 <div class="line">  <span class="comment">// ...</span></div>
 203 <div class="line"> </div>
 204 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a>();                 <span class="comment">// Initialize CMSIS-RTOS</span></div>
 205 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a>(app_main, NULL, NULL);    <span class="comment">// Create application main thread</span></div>
 206 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>();                      <span class="comment">// Start thread execution</span></div>
 207 <div class="line">  <span class="keywordflow">for</span> (;;) {}</div>
 208 <div class="line">}</div>
 209 <div class="ttc" id="acmsis__os2_8h_html"><div class="ttname"><a href="cmsis__os2_8h.html">cmsis_os2.h</a></div></div>
 210 <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>
 211 <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>
 212 <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>
 213 </div><!-- fragment --> </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>