begriffs open source - cmsis-freertos/blob - main/tech_data.html

   1 <!-- HTML header for doxygen 1.9.2-->
   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">
   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-FreeRTOS: Technical data and limitations</title>
   9 <link href="tabs.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="footer.js"></script>
  13 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  14 <script type="text/javascript" src="resize.js"></script>
  15 <script type="text/javascript" src="navtreedata.js"></script>
  16 <script type="text/javascript" src="navtree.js"></script>
  17 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  18 <script type="text/javascript" src="search/searchdata.js"></script>
  19 <script type="text/javascript" src="search/search.js"></script>
  20 <script type="text/javascript">
  21 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  22   $(document).ready(function() { init_search(); });
  23 /* @license-end */
  24 </script>
  25 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  26 <link href="version.css" rel="stylesheet" type="text/css" />
  27 <script type="text/javascript" src="../version.js"></script>
  28 </head>
  29 <body>
  30 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  31 <div id="titlearea">
  32 <table cellspacing="0" cellpadding="0">
  33  <tbody>
  34  <tr style="height: 55px;">
  35   <td id="projectlogo" style="padding: 1.5em;"><img alt="Logo" src="cmsis_logo_white_small.png"/></td>
  36   <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
  37    <div id="projectname">CMSIS-FreeRTOS
  38    &#160;<span id="projectnumber"><script type="text/javascript">
  39      <!--
  40      writeHeader.call(this);
  41      writeVersionDropdown(this);
  42      //-->
  43     </script>
  44    </span>
  45    </div>
  46    <div id="projectbrief">CMSIS-RTOS2 compliant FreeRTOS Implementation</div>
  47   </td>
  48   <!--END !PROJECT_NAME-->
  49    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
  50         <span class="left">
  51           <img id="MSearchSelect" src="search/mag_sel.svg"
  52                onmouseover="return searchBox.OnSearchSelectShow()"
  53                onmouseout="return searchBox.OnSearchSelectHide()"
  54                alt=""/>
  55           <input type="text" id="MSearchField" value="Search" accesskey="S"
  56                onfocus="searchBox.OnSearchFieldFocus(true)"
  57                onblur="searchBox.OnSearchFieldFocus(false)"
  58                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  59           </span><span class="right">
  60             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
  61           </span>
  62         </div>
  63 </td>
  64  </tr>
  65  </tbody>
  66 </table>
  67 </div>
  68 <!-- end header part -->
  69 <!-- Generated by Doxygen 1.9.2 -->
  70 <script type="text/javascript">
  71 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  72 var searchBox = new SearchBox("searchBox", "search",'Search','.html');
  73 /* @license-end */
  74 </script>
  75 </div><!-- top -->
  76 <div id="side-nav" class="ui-resizable side-nav-resizable">
  77   <div id="nav-tree">
  78     <div id="nav-tree-contents">
  79       <div id="nav-sync" class="sync"></div>
  80     </div>
  81   </div>
  82   <div id="splitbar" style="-moz-user-select:none;"
  83        class="ui-resizable-handle">
  84   </div>
  85 </div>
  86 <script type="text/javascript">
  87 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  88 $(document).ready(function(){initNavTree('tech_data.html',''); initResizable(); });
  89 /* @license-end */
  90 </script>
  91 <div id="doc-content">
  92 <!-- window showing the filter options -->
  93 <div id="MSearchSelectWindow"
  94      onmouseover="return searchBox.OnSearchSelectShow()"
  95      onmouseout="return searchBox.OnSearchSelectHide()"
  96      onkeydown="return searchBox.OnSearchSelectKey(event)">
  97 </div>
  98
  99 <!-- iframe showing the search results (closed by default) -->
 100 <div id="MSearchResultsWindow">
 101 <iframe src="javascript:void(0)" frameborder="0"
 102         name="MSearchResults" id="MSearchResults">
 103 </iframe>
 104 </div>
 105
 106 <div><div class="header">
 107   <div class="headertitle"><div class="title">Technical data and limitations </div></div>
 108 </div><!--header-->
 109 <div class="contents">
 110 <div class="textblock"><p >This lists the technical data of CMSIS-FreeRTOS.</p>
 111 <h1><a class="anchor" id="td_limitations"></a>
 112 Limitations</h1>
 113 <p >The following list briefly describes the limitations and unsupported features of the CMSIS-RTOS2 wrapper for FreeRTOS:</p><ul>
 114 <li>Static memory allocation will only work if <em>all</em> memory (from attributes structure) is provided statically. In order to allocate object memory statically, you need to:<ul>
 115 <li>provide the memory for control blocks and stack in the <code>osThreadAttr_t</code> structure for threads.</li>
 116 <li>provide the memory for control blocks and message data in the <code>osMessageQueueAttr_t</code> structure for memory queues.</li>
 117 <li>provide the memory for control blocks for other objects in the object's attributes structure.</li>
 118 </ul>
 119 </li>
 120 <li>Each timer object requires additional 8 bytes of memory:<ul>
 121 <li>to allocate all memory statically, provide the memory for control block of size (sizeof(StaticTimer_t) + 8 bytes)</li>
 122 <li>otherwise, additional 8 bytes of dynamic memory will be used</li>
 123 </ul>
 124 </li>
 125 <li><code>osKernelSuspend</code> and <code>osKernelResume</code> are not supported.</li>
 126 <li><code>osThreadDetach</code>, <code>osThreadJoin()</code> and attribute <code>osThreadJoinable</code> are not supported (<code>osThreadNew</code> returns NULL when osThreadJoinable attribute is specified).</li>
 127 <li><code>osThreadGetStackSize</code> is not implemented.</li>
 128 <li>Event flags are limited to 24 bits.</li>
 129 <li><code>osEventFlagsGetName</code> is not implemented.</li>
 130 <li><code>osEventFlagsWait</code> cannot be called from an ISR.</li>
 131 <li>Priority inherit protocol is used as default mutex behavior (<code>osMutexNew</code> creates priority inherit mutex object by default and ignores <code>osMutexPrioInherit</code> attribute when specified).</li>
 132 <li>Robust mutex objects are not supported (<code>osMutexNew</code> returns NULL when <code>osMutexRobust</code> attribute is specified).</li>
 133 <li><code>osMutexGetName</code> is not implemented and always returns NULL.</li>
 134 <li><code>osSemaphoreGetName</code> is not implemented and always returns NULL.</li>
 135 <li><code>osMessageQueueGetName</code> is not implemented and always returns NULL.</li>
 136 <li><code>osMessageQueuePut</code> and <code>osMessageQueueGet</code> always ignore message priority.</li>
 137 </ul>
 138 <h1><a class="anchor" id="td_validation"></a>
 139 Validation suite results</h1>
 140 <p >CMSIS provides a <a href="https://arm-software.github.io/CMSIS_5/RTOS2/html/rtosValidation.html" target="_blank">CMSIS-RTOS2 validation suite</a> that can be used to test a real-time operating system for compliance to the standard. The test suite has been executed successfully on the CMSIS-FreeRTOS implementation (<a href="cmsis_rtos2_validation.txt">see results</a>).</p>
 141 <p >The following table explains the exceptions:</p>
 142 <table class="doxtable" summary="Validation Exceptions">
 143 <tr>
 144 <th>Test Case </th><th>Result </th><th>Reason </th><th>Summary  </th></tr>
 145 <tr>
 146 <td>TC_osKernelGetState_2 </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to call <code>osKernelGetState</code> after a <code>osKernelSuspend</code> call. osKernelSuspend is not implemented.   </td></tr>
 147 <tr>
 148 <td>TC_osKernelLock_2 </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to call <code>osKernelLock</code> after a <code>osKernelSuspend</code> call. <code>osKernelSuspend</code> is not implemented.   </td></tr>
 149 <tr>
 150 <td>TC_osKernelUnlock_2 </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to call <code>osKernelUnlock</code> after a <code>osKernelSuspend</code> call. <code>osKernelSuspend</code> is not implemented.   </td></tr>
 151 <tr>
 152 <td>TC_osKernelSuspend_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osKernelSuspend</code> which is not implemented.   </td></tr>
 153 <tr>
 154 <td>TC_osKernelResume_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osKernelResume</code> which is not implemented.   </td></tr>
 155 <tr>
 156 <td>TC_osThreadNew_3 </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to create joinable thread using <code>osThreadJoinable</code> attribute. FreeRTOS does not support joinable threads.   </td></tr>
 157 <tr>
 158 <td>TC_osThreadGetName_1 </td><td>failed </td><td>deviation </td><td>Test attempt to retrieve a name on an unnamed thread. An empty string is returned instead of NULL pointer.   </td></tr>
 159 <tr>
 160 <td>TC_osThreadGetState_3 </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to retrieve a state of a terminated joinable thread. FreeRTOS does not support joinable threads.   </td></tr>
 161 <tr>
 162 <td>TC_osThreadDetach_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osThreadDetach</code> which is not implemented.   </td></tr>
 163 <tr>
 164 <td>TC_osThreadDetach_2 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osThreadDetach</code> which is not implemented.   </td></tr>
 165 <tr>
 166 <td>TC_osThreadJoin_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osThreadJoin</code> which is not implemented.   </td></tr>
 167 <tr>
 168 <td>TC_osThreadJoin_2 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osThreadJoin</code> which is not implemented.   </td></tr>
 169 <tr>
 170 <td>TC_osThreadJoin_3 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osThreadJoin</code> which is not implemented.   </td></tr>
 171 <tr>
 172 <td>TC_osThreadGetStackSize_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osThreadGetStackSize</code> which is not implemented.   </td></tr>
 173 <tr>
 174 <td>TC_ThreadReturn </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to terminate a thread by just returning from a thread. FreeRTOS threads may not return.   </td></tr>
 175 <tr>
 176 <td>TC_osEventFlagsSet_1 </td><td>failed </td><td>deviation </td><td>Test attempts to set event flags by calling <code>osEventFlagsSet</code> multiple times without leaving ISR handler.<br  />
 177  To process ISR requests, FreeRTOS uses timer deamon which wakes-up after ISR execution.   </td></tr>
 178 <tr>
 179 <td>TC_osEventFlagsClear_1 </td><td>failed </td><td>deviation </td><td>Test attempts to clear event flags by calling <code>osEventFlagsClear</code> multiple times without leaving ISR handler.<br  />
 180  To process ISR requests, FreeRTOS uses timer deamon which wakes-up after ISR execution.   </td></tr>
 181 <tr>
 182 <td>TC_osEventFlagsWait_1 </td><td>failed </td><td>unsupported feature </td><td>Test attempts to wait for flags from ISR with zero timeout (try-semantic). FreeRTOS does not support such operation.   </td></tr>
 183 <tr>
 184 <td>TC_osEventFlagsGetName_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osEventFlagsGetName</code> which is not implemented.   </td></tr>
 185 <tr>
 186 <td>TC_osMutexNew_4 </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to create a robust mutex. FreeRTOS implementation does not support robust mutexes.   </td></tr>
 187 <tr>
 188 <td>TC_osMutexGetName_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osMutexGetName</code> which is not implemented.   </td></tr>
 189 <tr>
 190 <td>TC_MutexRobust </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to validate robust mutex behavior. FreeRTOS implementation does not support robust mutexes.   </td></tr>
 191 <tr>
 192 <td>TC_MutexOwnership </td><td>not executed </td><td>unsupported feature </td><td>Test attempts to release a mutex from a thread which is not the mutex owner.<br  />
 193  FreeRTOS implementation does not verify ownership on mutex release.   </td></tr>
 194 <tr>
 195 <td>TC_osSemaphoreGetName_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osSemaphoreGetName</code> which is not implemented.   </td></tr>
 196 <tr>
 197 <td>TC_osMessageQueueGetName_1 </td><td>not executed </td><td>unsupported feature </td><td>Test validates <code>osMessageQueueGetName</code> which is not implemented.   </td></tr>
 198 </table>
 199 <h1><a class="anchor" id="td_troubleshooting"></a>
 200 Troubleshooting</h1>
 201 <p >Users looking for help shall check <a href="https://freertos.org/FAQHelp.html">subsection of the full FreeRTOS FAQ</a>. It contains many useful information that also apply when using FreeRTOS in context of CMSIS-FreeRTOS.</p>
 202 <p >Additionally, please take a look at the following:</p>
 203 <ol>
 204 <li>
 205 <b>Interrupts are disabled when main is called or before the kernel is started</b> <br  />
 206  Before the FreeRTOS kernel is started, threads (i.e. tasks) may be created together with other objects like mutexes, semaphores, message queues etc. When functions like xTaskCreate, xSemaphoreCreateMutex, xQueueCreate and others get called, they prevent interrupt handlers from calling FreeRTOS API functions in order to keep FreeRTOS kernel variables and state machine consistent (see also here <a href="https://freertos.org/FAQHelp.html">Interrupts are not executing</a>). <br  />
 207  In cases when interrupts may be executed after object creation and before the FreeRTOS kernel is started they can be re-enabled: <div class="fragment"><div class="line">portENABLE_INTERRUPTS();</div>
 208 </div><!-- fragment --> Make sure that the interrupts you execute in such case do not call FreeRTOS API.  </li>
 209 </ol>
 210 </div></div><!-- contents -->
 211 </div><!-- PageDoc -->
 212 </div><!-- doc-content -->
 213 <!-- start footer part -->
 214 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 215   <ul>
 216     <li class="footer">
 217       <script type="text/javascript">
 218         <!--
 219         writeFooter.call(this);
 220         //-->
 221       </script>
 222     </li>
 223   </ul>
 224 </div>
 225 </body>
 226 </html>