begriffs open source - cmsis/blob - main/RTOS2/usingOS2.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: Using CMSIS-RTOS2 Interface</title>
   9 <link href="doxygen.css" rel="stylesheet" type="text/css" />
  10 <script type="text/javascript" src="jquery.js"></script>
  11 <script type="text/javascript" src="dynsections.js"></script>
  12 <script type="text/javascript" src="tabs.js"></script>
  13 <script type="text/javascript" src="footer.js"></script>
  14 <script type="text/javascript" src="navtree.js"></script>
  15 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  16 <script type="text/javascript" src="resize.js"></script>
  17 <script type="text/javascript" src="navtreedata.js"></script>
  18 <script type="text/javascript" src="navtree.js"></script>
  19 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  20 <script type="text/javascript" src="search/searchdata.js"></script>
  21 <script type="text/javascript" src="search/search.js"></script>
  22 <script type="text/javascript">
  23 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  24   $(document).ready(function() { init_search(); });
  25 /* @license-end */
  26 </script>
  27 <script type="text/javascript" src="darkmode_toggle.js"></script>
  28 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  29 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  30 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  31 <link href="extra_tabs.css" rel="stylesheet" type="text/css"/>
  32 <link href="version.css" rel="stylesheet" type="text/css"/>
  33 <script type="text/javascript" src="../../version.js"></script>
  34 </head>
  35 <body>
  36 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  37 <div id="titlearea">
  38 <table cellspacing="0" cellpadding="0">
  39  <tbody>
  40  <tr style="height: 55px;">
  41   <td id="projectlogo" style="padding: 1.5em;"><img alt="Logo" src="cmsis_logo_white_small.png"/></td>
  42   <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
  43    <div id="projectname">CMSIS-RTOS2
  44    &#160;<span id="projectnumber"><script type="text/javascript">
  45      <!--
  46      writeHeader.call(this);
  47      writeVersionDropdown.call(this, "CMSIS-RTOS2");
  48      //-->
  49     </script>
  50    </span>
  51    </div>
  52    <div id="projectbrief">Real-Time Operating System API</div>
  53   </td>
  54    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
  55         <span class="left">
  56           <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
  57           <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
  58                onfocus="searchBox.OnSearchFieldFocus(true)"
  59                onblur="searchBox.OnSearchFieldFocus(false)"
  60                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  61           </span><span class="right">
  62             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
  63           </span>
  64         </div>
  65 </td>
  66   <!--END !PROJECT_NAME-->
  67  </tr>
  68  </tbody>
  69 </table>
  70 </div>
  71 <!-- end header part -->
  72 <div id="CMSISnav" class="tabs1">
  73   <ul class="tablist">
  74     <script type="text/javascript">
  75       writeComponentTabs.call(this);
  76     </script>
  77   </ul>
  78 </div>
  79 <script type="text/javascript">
  80   writeSubComponentTabs.call(this);
  81 </script>
  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('usingOS2.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">Using CMSIS-RTOS2 Interface </div></div>
 128 </div><!--header-->
 129 <div class="contents">
 130 <div class="textblock"><p><a class="anchor" id="md_src_using"></a> This sections explains concepts for using CMSIS-RTOS2 interface. They are recommeded to follow for best reusability of the software across different platforms.</p>
 131 <ul>
 132 <li><a class="el" href="usingOS2.html#rtos2_functionalities">Functionality overview</a> lists the OS services supported by CMSIS-RTOS2 API.</li>
 133 <li><a class="el" href="usingOS2.html#cmsis_os2_h">cmsis_os2.h API header file</a> explains how CMSIS-RTOS2 interface is defined and can be used along with the RTOS-specific files as well as part of CMSIS pack.</li>
 134 <li><a class="el" href="usingOS2.html#SystemStartup">System Startup</a> shows the flow for kernel initialization.</li>
 135 <li><a class="el" href="usingOS2.html#rtos_objects">Lifecycle of RTOS Objects</a> explains the approach to creating and using RTOS Objects.</li>
 136 <li><a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt">Memory Management</a> provides information about options for memory management with CMSIS-RTOS2.</li>
 137 <li><a class="el" href="CMSIS_RTOS_ProcessIsolation.html">Process Isolation</a> describes the CMSIS-RTOS2 concepts for protecting execution of critical software tasks against potential flaws in other parts of a program.</li>
 138 </ul>
 139 <blockquote class="doxtable">
 140 <p>&zwj;<b>Note</b></p><ul>
 141 <li>For the guidance on migration from CMSIS-RTOS API v1 to CMSIS-RTOS2, see section <a href="https://arm-software.github.io/CMSIS_5/latest/RTOS2/html/os2MigrationFunctions.html">Detailed API Function Differences</a> in CMSIS 5 documentation. </li>
 142 </ul>
 143 </blockquote>
 144 <h1><a class="anchor" id="rtos2_functionalities"></a>
 145 Functionality overview</h1>
 146 <p>The CMSIS-RTOS2 defines APIs for common RTOS services as listed below:</p>
 147 <ul>
 148 <li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html">Kernel Information and Control</a> provides system information and controls the RTOS Kernel.</li>
 149 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html">Thread Management</a> allows you to define, create, and control RTOS threads (tasks).</li>
 150 <li><a class="el" href="group__CMSIS__RTOS__Wait.html">Generic Wait Functions</a> for controlling time delays. Also see <a class="el" href="usingOS2.html#CMSIS_RTOS_TimeOutValue">Timeout Values</a>.</li>
 151 <li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html">Timer Management</a> functions are used to trigger the execution of functions.</li>
 152 <li>Three different event types support communication between multiple threads and/or ISR:<ul>
 153 <li><a class="el" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html">Thread Flags</a>: may be used to indicate specific conditions to a thread.</li>
 154 <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>
 155 <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>
 156 </ul>
 157 </li>
 158 <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>
 159 </ul>
 160 <p>The referenced pages contain theory of operation for corresponding services as well as detailed API description with example code.</p>
 161 <h1><a class="anchor" id="cmsis_os2_h"></a>
 162 cmsis_os2.h API header file</h1>
 163 <p>The <b>CMSIS-RTOS2</b> interface is provided in <b>cmsis_os2.h</b> file - a standard C header file that user applications and middleware components need to include to access CMSIS-RTOS2 API. It contains all the function declarations, as well as type and macro definitions.</p>
 164 <p>An implementation specific header file (<em>rtos</em>.h in the picture below) provides access to such definitions. Using the <b>cmsis_os2.h</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>
 165 <div class="image">
 166 <img src="CMSIS_RTOS_Files.png" alt=""/>
 167 <div class="caption">
 168 CMSIS-RTOS File Structure</div></div>
 169     <p>Once the files are added to a project, the user can start working with the CMSIS-RTOS functions.</p>
 170 <p>CMSIS-RTOS2 is especially easy use to integrate in projects that support <a href="https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/index.html">CMSIS-Pack format</a>. CMSIS-RTOS2 is provided in the <a href="../General/cmsis_pack.html">CMSIS 6 Software Pack</a> as a software component in form of <a href="https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_Packs.html#cp_APIDef">a central API defintion</a> It is part of component class <b>CMSIS</b> and belongs to component group <b>RTOS2</b>.</p>
 171 <h1><a class="anchor" id="cmsis_os2_coding_rules"></a>
 172 Coding Rules</h1>
 173 <p>CMSIS-RTOS2 follows <a href="../General/index.html#coding_rules">the general CMSIS coding rules</a>. Additionally following Namespace prefixes are used in CMSIS-RTOS2 API:</p>
 174 <ul>
 175 <li><code>os</code> for all definitions and function names. Examples: <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga7c2b7db42d23e4f56132e0ed739d02e5">osThreadPrivileged</a>, <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>.</li>
 176 <li><code>os</code> with postfix <code>_t</code> for all typedefs. Examples: <a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a>, <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#structosThreadAttr__t">osThreadAttr_t</a>.</li>
 177 </ul>
 178 <h1><a class="anchor" id="SystemStartup"></a>
 179 System Startup</h1>
 180 <p>When program execution reaches <code>main()</code> function there is a recommended order to initialize the hardware and start the kernel.</p>
 181 <p>Your application's <code>main()</code> should implement at least the following in the given order:</p>
 182 <ol type="1">
 183 <li>Initialize and configure hardware including peripherals, memory, pins, clocks and the interrupt system.</li>
 184 <li>Update the system core clock using the respective <a href="../Core/group__system__init__gr.html">CMSIS-Core (Cortex-M)</a>  or <a href="../Core_A/group__system__init__gr.html">CMSIS-Core (Cortex-A)</a>  function.</li>
 185 <li>Initialize the RTOS kernel using <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a>.</li>
 186 <li>Optionally, create one thread (for example <code>app_main</code>) using <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a>, which will be used as a main thread . This thread should take care of creating and starting objects, once it is run by the scheduler. Alternatively, threads can be created directly in <code>main()</code>.</li>
 187 <li>Start the RTOS scheduler using <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a> which also configures the system tick timer and initializes RTOS specific interrupts. This function does not return in case of successful execution. Therefore, any application code after <code>osKernelStart</code> will not be executed.</li>
 188 </ol>
 189 <blockquote class="doxtable">
 190 <p>&zwj;<b>Note</b></p><ul>
 191 <li>Modifying priorities and groupings in the NVIC by the application after the above sequence is not recommended.</li>
 192 <li>Before executing <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>, only the functions <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga6f7764e7250c5c5364c00c45a5d1d199">osKernelGetInfo</a>, <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga48b69b81012fce051f639be288b243ba">osKernelGetState</a>, and object creation functions (osXxxNew) may be called. </li>
 193 </ul>
 194 </blockquote>
 195 <p><b>Code Example</b></p>
 196 <div class="fragment"><div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div>
 197 <div class="line"><span class="comment"> * CMSIS-RTOS &#39;main&#39; function template</span></div>
 198 <div class="line"><span class="comment"> *---------------------------------------------------------------------------*/</span></div>
 199 <div class="line"> </div>
 200 <div class="line"><span class="preprocessor">#include &quot;RTE_Components.h&quot;</span></div>
 201 <div class="line"><span class="preprocessor">#include  CMSIS_device_header</span></div>
 202 <div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 203 <div class="line"> </div>
 204 <div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div>
 205 <div class="line"><span class="comment"> * Application main thread</span></div>
 206 <div class="line"><span class="comment"> *---------------------------------------------------------------------------*/</span></div>
 207 <div class="line"><span class="keywordtype">void</span> app_main (<span class="keywordtype">void</span> *argument) {</div>
 208 <div class="line"> </div>
 209 <div class="line">  <span class="comment">// ...</span></div>
 210 <div class="line">  <span class="keywordflow">for</span> (;;) {}</div>
 211 <div class="line">}</div>
 212 <div class="line"> </div>
 213 <div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
 214 <div class="line"> </div>
 215 <div class="line">  <span class="comment">// System Initialization</span></div>
 216 <div class="line">  SystemCoreClockUpdate();</div>
 217 <div class="line">  <span class="comment">// ...</span></div>
 218 <div class="line"> </div>
 219 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659" title="Initialize the RTOS Kernel.">osKernelInitialize</a>();                 <span class="comment">// Initialize CMSIS-RTOS</span></div>
 220 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f" title="Create a thread and add it to Active Threads.">osThreadNew</a>(app_main, NULL, NULL);    <span class="comment">// Create application main thread</span></div>
 221 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221" title="Start the RTOS Kernel scheduler.">osKernelStart</a>();                      <span class="comment">// Start thread execution</span></div>
 222 <div class="line">  <span class="keywordflow">for</span> (;;) {}</div>
 223 <div class="line">}</div>
 224 </div><!-- fragment --><h1><a class="anchor" id="rtos_objects"></a>
 225 Lifecycle of RTOS Objects</h1>
 226 <p>All RTOS objects share a common design concept. The overall life-cycle of an object can be summarized as created -&gt; in use -&gt; destroyed.</p>
 227 <h2><a class="anchor" id="rtos_objects_create"></a>
 228 Create Objects</h2>
 229 <p>An RTOS object (thread, timer, flags, mutex, etc.) is created by calling its <code>osXxxNew</code> function (for example <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a>, <a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#gad4e7f785c5f700a509f55a3bf6a62bec">osTimerNew</a>, <a class="el" href="group__CMSIS__RTOS__EventFlags.html#gab14b1caeb12ffa42cce1bfe889cd07df">osEventFlagsNew</a>, etc). The new function returns a numeric identifier that can be used to operate with the new object.</p>
 230 <p>The actual state of an object is typically stored in an object specific control block. The memory layout (and size needed) for the control block is implementation specific. One should not make any specific assumptions about the control block. The control block layout might change and hence should be seen as an implementation internal detail.</p>
 231 <p>In order to expose control about object specific options all <code>osXxxNew</code> functions provide an optional <code>attr</code> argument, which can be left as <span class="XML-Token">NULL</span> by default. It takes a pointer to an object specific attribute structure, commonly containing the fields:</p>
 232 <ul>
 233 <li><code>name</code> to attach a human readable name to the object for identification,</li>
 234 <li><code>attr_bits</code> to control object-specific options,</li>
 235 <li><code>cb_mem</code> to provide memory for the control block manually, and</li>
 236 <li><code>cb_size</code> to quantify the memory size provided for the control block.</li>
 237 </ul>
 238 <p>The <code>name</code> attribute is only used for object identification, e.g. using RTOS-aware debugging. The attached string is not used for any other purposes internally.</p>
 239 <p>The <code>cb_mem</code> and <code>cb_size</code> attributes can be used to provide memory for the control block manually instead of relying on the implementation internal memory allocation. One has to assure that the amount of memory pointed to by <code>cb_mem</code> is sufficient for the objects control block structure. If the size given as <code>cb_size</code> is not sufficient the <code>osXxxNew</code> function returns with an error, i.e. returning <span class="XML-Token">NULL</span>. Furthermore providing control block memory manually is less portable. Thus one has to take care about implementation specific alignment and placement requirements for instance. Refer to <a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt">Memory Management</a> for further details.</p>
 240 <h2><a class="anchor" id="rtos_objects_usage"></a>
 241 Object Usage</h2>
 242 <p>After an object has been created successfully it can be used until it is destroyed. The actions defined for an object depends on its type. Commonly all the <code>osXxxDoSomething</code> access function require the reference to the object to work with as the first <code>xxx_id</code> parameter.</p>
 243 <p>The access function can be assumed to apply some sort of sanity checking on the id parameter. So that it is assured one cannot accidentally call an access function with a <span class="XML-Token">NULL</span> object reference. Furthermore the concrete object type is verified, i.e. one cannot call access functions of one object type with a reference to another object type.</p>
 244 <p>All further parameter checks applied are either object and action specific or may even be implementation specific. Thus one should always check action function return values for <code>osErrorParameter</code> to assure the provided arguments were accepted.</p>
 245 <p>As a rule of thumb only non-blocking access function can be used from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a> (ISR). This incorporates <code>osXxxWait</code> functions (and similar) limited to be called with parameter <code>timeout</code> set to <span class="XML-Token">0</span>, i.e. usage of try-semantics.</p>
 246 <h2><a class="anchor" id="rtos_objects_delete"></a>
 247 Object Destruction</h2>
 248 <p>Objects that are not needed anymore can be destructed on demand to free the control block memory. Objects are not destructed implicitly. Thus one can assume an object id to be valid until <code>osXxxDelete</code> is called explicitly. The delete function finally frees the control block memory. In case of user provided control block memory, see above, the memory must be freed manually as well.</p>
 249 <p>The only exception one has to take care of are Threads which do not have an explicit <code>osThreadDelete</code> function. Threads can either be <code>detached</code> or <code>joinable</code>. Detached threads are automatically destroyed on termination, i.e. call to <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga2f8ba6dba6e9c065a6e236ffd410d74a">osThreadTerminate</a> or <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gaddaa452dd7610e4096647a566d3556fc">osThreadExit</a> or return from thread function. On the other hand joinable threads are kept alive until one explicitly calls <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga3fca90fb0679afeb968aa8c3d5874487">osThreadJoin</a>.</p>
 250 <h1><a class="anchor" id="CMSIS_RTOS_TimeOutValue"></a>
 251 Timeout Values</h1>
 252 <p>Timeout value is an argument in many API functions that allows to set the maximum time delay for resolving a request. The timeout value specifies the number of timer ticks until the time delay elapses. The value is an upper bound and depends on the actual time elapsed since the last timer tick.</p>
 253 <p>Examples:</p>
 254 <ul>
 255 <li>timeout value <b>0</b> : the system does not wait, even when no resource is available the RTOS function returns instantly.</li>
 256 <li>timeout value <b>1</b> : the system waits until the next timer tick occurs; depending on the previous timer tick, it may be a very short wait time.</li>
 257 <li>timeout value <b>2</b> : actual wait time is between 1 and 2 timer ticks.</li>
 258 <li>timeout value <a class="el" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb">osWaitForever</a> : system waits infinite until a resource becomes available. Or one forces the thread to resume using <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga3dbad90eff394b02de76a452c84c5d80">osThreadResume</a> which is discouraged.</li>
 259 </ul>
 260 <div class="image">
 261 <img src="TimerValues.png" alt=""/>
 262 <div class="caption">
 263 Example of timeout using osDelay()</div></div>
 264     <ul>
 265 <li>CPU time can be scheduled with the following functionalities:<ul>
 266 <li>A <em>timeout</em> parameter is incorporated in many CMSIS-RTOS2 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>
 267 <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>
 268 <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>
 269 </ul>
 270 </li>
 271 </ul>
 272 <h1><a class="anchor" id="CMSIS_RTOS_ISR_Calls"></a>
 273 Calls from Interrupt Service Routines</h1>
 274 <p>The following CMSIS-RTOS2 functions can be called from threads and Interrupt Service Routines (ISR):</p>
 275 <ul>
 276 <li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga6f7764e7250c5c5364c00c45a5d1d199">osKernelGetInfo</a>, <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga48b69b81012fce051f639be288b243ba">osKernelGetState</a>, <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga84bcdbf2fb76b10c8df4e439f0c7e11b">osKernelGetTickCount</a>, <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga7a8d7bd927eaaa58999f91d7d6310cee">osKernelGetTickFreq</a>, <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae0fcaff6cecfb4013bb556c87afcd7d2">osKernelGetSysTimerCount</a>, <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga4d69215a93220f72be3684cad582f16a">osKernelGetSysTimerFreq</a></li>
 277 <li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gac3230f3a55a297514b013ebf38f27e0a">osThreadGetName</a>, <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga8df03548e89fbc56402a5cd584a505da">osThreadGetId</a>, <a class="el" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html#ga6f89ef9caded1d9963c7b12b0f6412c9">osThreadFlagsSet</a></li>
 278 <li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#ga7938dde88ada1a01b60f41cf120069c0">osTimerGetName</a></li>
 279 <li><a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga59f4ddf0ee8c395b1672bb978d1cfc88">osEventFlagsGetName</a>, <a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga33b71d14cecf90b4e72639dd19f23a5e">osEventFlagsSet</a>, <a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga93bf258ca0007c6641fbe8e4f2b8a1e5">osEventFlagsClear</a>, <a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga8bda3185f46bfd278cea8a6cf357677d">osEventFlagsGet</a>, <a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga52acb34a8322e58020227344fe662b4e">osEventFlagsWait</a></li>
 280 <li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga00b5e58cd247a412d1afd18732d8b752">osMutexGetName</a></li>
 281 <li><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga9586952051f00285f1482dbe6695bbc4">osSemaphoreGetName</a>, <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga7e94c8b242a0c81f2cc79ec22895c87b">osSemaphoreAcquire</a>, <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga0abcee1b5449d7a6928fb9248c690bb6">osSemaphoreRelease</a>, <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga7559d4dff3cda9992fc5ab5de3e74c70">osSemaphoreGetCount</a></li>
 282 <li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gab414a1e138205a55820acfa277c8f386">osMemoryPoolGetName</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga8ead54e99ccb8f112356c88f99d38fbe">osMemoryPoolAlloc</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gabb4f4560daa6d1f8c8789082ee186d16">osMemoryPoolFree</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gad696e94bfbe28f0b6613f9303fdf6a37">osMemoryPoolGetCapacity</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gab2bf059b7fa7679c3cccdaeec60b6c0e">osMemoryPoolGetBlockSize</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga958a9449bff8c95ce213de98eef5739d">osMemoryPoolGetCount</a>, <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga0394cffa9479a7994e3b03c79c1cb909">osMemoryPoolGetSpace</a></li>
 283 <li><a class="el" href="group__CMSIS__RTOS__Message.html#gae7cf7bf2b97a5ae481fb60fcce99247a">osMessageQueueGetName</a>, <a class="el" href="group__CMSIS__RTOS__Message.html#gaa515fc8b956f721a8f72b2c505813bfc">osMessageQueuePut</a>, <a class="el" href="group__CMSIS__RTOS__Message.html#gad90d4959466a7a65105061da8256ab9e">osMessageQueueGet</a>, <a class="el" href="group__CMSIS__RTOS__Message.html#gac24f87d4f395e9e9c900c320e45ade8a">osMessageQueueGetCapacity</a>, <a class="el" href="group__CMSIS__RTOS__Message.html#ga96d3d84069b20359de48109e28a1a89e">osMessageQueueGetMsgSize</a>, <a class="el" href="group__CMSIS__RTOS__Message.html#ga6a32ac394fcff568b251c160cc3014b2">osMessageQueueGetCount</a>, <a class="el" href="group__CMSIS__RTOS__Message.html#gaddf0904427436dd3880d46263c2dc9fa">osMessageQueueGetSpace</a></li>
 284 </ul>
 285 <p>Functions that cannot be called from an ISR are verifying the interrupt status and return the status code <a class="el" href="group__CMSIS__RTOS__Definitions.html#gga6c0dbe6069e4e7f47bb4cd32ae2b813ea91c2ea9c9cd03401ff7d396c636d1864">osErrorISR</a>, in case they are called from an ISR context. In some implementations, this condition might be caught using the HARD_FAULT</p>
 286 <h1><a class="anchor" id="CMSIS_RTOS_MemoryMgmt"></a>
 287 Memory Management</h1>
 288 <p>The <a class="el" href="group__CMSIS__RTOS.html">CMSIS-RTOS2 API</a> offers two options for memory management the user can choose. For object storage one can either use</p>
 289 <ul>
 290 <li><a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt_Automatic">Automatic Dynamic Allocation</a> (fully portable), or</li>
 291 <li><a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt_Manual">Manual User-defined Allocation</a> (implementation specific).</li>
 292 </ul>
 293 <p>In order to affect the memory allocation scheme all RTOS objects that can be created on request, i.e. those having a <code>osXxxNew</code> function, accept an optional <code>osXxxAttr_t attr</code> argument on creation. As a rule of thumb the object attributes at least have members to assign custom control block memory, i.e. <code>cb_mem</code> and <code>cb_size</code> members. By default, i.e. <code>attr</code> is <code>NULL</code> or <code>cb_mem</code> is <code>NULL</code>, <a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt_Automatic">Automatic Dynamic Allocation</a> is used. Providing a pointer to user memory in <code>cb_mem</code> switches to <a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt_Manual">Manual User-defined Allocation</a>.</p>
 294 <h2><a class="anchor" id="CMSIS_RTOS_MemoryMgmt_Automatic"></a>
 295 Automatic Dynamic Allocation</h2>
 296 <p>The automatic allocation is the default and viable for many use-cases. Moreover it is fully portable across different implementations of the <a class="el" href="group__CMSIS__RTOS.html">CMSIS-RTOS2 API</a>. The common drawback of dynamic memory allocation is the possibility of memory fragmentation and exhaustion. Given that all needed objects are created once upon system initialization and never deleted at runtime this class of runtime failures can be prevented, though.</p>
 297 <p>The actual allocation strategy used is implementation specific, i.e. whether global heap or preallocated memory pools are used.</p>
 298 <p><b>Code Example:</b></p>
 299 <div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span>                          <span class="comment">// CMSIS-RTOS2 API header</span></div>
 300 <div class="line">  </div>
 301 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
 302 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex2_id;</div>
 303 <div class="line">  </div>
 304 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 305 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,                              <span class="comment">// human readable mutex name</span></div>
 306 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926" title="Recursive mutex.">osMutexRecursive</a> | <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599" title="Priority inherit protocol.">osMutexPrioInherit</a>,        <span class="comment">// attr_bits</span></div>
 307 <div class="line">  NULL,                                         <span class="comment">// memory for control block (default)</span></div>
 308 <div class="line">  0U                                            <span class="comment">// size for control block (default)</span></div>
 309 <div class="line">};</div>
 310 <div class="line">  </div>
 311 <div class="line"><span class="keywordtype">void</span> CreateMutex (<span class="keywordtype">void</span>)  {</div>
 312 <div class="line">  mutex_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8" title="Create and Initialize a Mutex object.">osMutexNew</a>(NULL);                  <span class="comment">// use default values for all attributes</span></div>
 313 <div class="line">  mutex2_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8" title="Create and Initialize a Mutex object.">osMutexNew</a>(&amp;Thread_Mutex_attr);   <span class="comment">// use attributes from defined structure</span></div>
 314 <div class="line">  :</div>
 315 <div class="line">}</div>
 316 </div><!-- fragment --><p>The Mutexes in this example are created using automatic memory allocation.</p>
 317 <h2><a class="anchor" id="CMSIS_RTOS_MemoryMgmt_Manual"></a>
 318 Manual User-defined Allocation</h2>
 319 <p>One can get fine grained control over memory allocation by providing user-defined memory. The actual requirements such user-defined memory are kernel-specific. Thus one needs to carefully refer to the size and alignment rules of the implementation used.</p>
 320 <p><b>Code Example:</b></p>
 321 <div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span>                          <span class="comment">// CMSIS-RTOS2 API header</span></div>
 322 <div class="line"><span class="preprocessor">#include &quot;rtx_os.h&quot;</span>                             <span class="comment">// kernel include file</span></div>
 323 <div class="line">  </div>
 324 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
 325 <div class="line">  </div>
 326 <div class="line"><span class="keyword">static</span> osRtxMutex_t mutex_cb __attribute__((section(<span class="stringliteral">&quot;.bss.os.mutex.cb&quot;</span>)));  <span class="comment">// Placed on .bss.os.mutex.cb section for RTX5 aware debugging</span></div>
 327 <div class="line">  </div>
 328 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 329 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,                              <span class="comment">// human readable mutex name</span></div>
 330 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926" title="Recursive mutex.">osMutexRecursive</a> | <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599" title="Priority inherit protocol.">osMutexPrioInherit</a>,        <span class="comment">// attr_bits</span></div>
 331 <div class="line">  &amp;mutex_cb,                                    <span class="comment">// memory for control block (user-defined)</span></div>
 332 <div class="line">  <span class="keyword">sizeof</span>(mutex_cb)                              <span class="comment">// size for control block (user-defined)</span></div>
 333 <div class="line">};</div>
 334 <div class="line">  </div>
 335 <div class="line"><span class="keywordtype">void</span> CreateMutex (<span class="keywordtype">void</span>)  {</div>
 336 <div class="line">  mutex_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8" title="Create and Initialize a Mutex object.">osMutexNew</a>(&amp;Thread_Mutex_attr);    <span class="comment">// use attributes from defined structure</span></div>
 337 <div class="line">  :</div>
 338 <div class="line">}</div>
 339 </div><!-- fragment --><p>The above example uses user-defined memory for the mutex control block. For this <code>mutex_cb</code> is defined with the control block type provided by the kernel header file <code>rtx_os.h</code> from CMSIS-RTX RTOS kernel. </p>
 340 </div></div><!-- contents -->
 341 </div><!-- PageDoc -->
 342 </div><!-- doc-content -->
 343 <!-- start footer part -->
 344 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 345   <ul>
 346     <li class="footer">
 347       <script type="text/javascript">
 348         <!--
 349         writeFooter.call(this);
 350         //-->
 351       </script>
 352     </li>
 353   </ul>
 354 </div>
 355 </body>
 356 </html>