begriffs open source - cmsis-freertos/blob - main/page_create_project.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-FreeRTOS: Create a FreeRTOS Project</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="navtreedata.js"></script>
  17 <script type="text/javascript" src="navtree.js"></script>
  18 <script type="text/javascript" src="resize.js"></script>
  19 <script type="text/javascript" src="cookie.js"></script>
  20 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  21 <script type="text/javascript" src="search/searchdata.js"></script>
  22 <script type="text/javascript" src="search/search.js"></script>
  23 <script type="text/javascript">
  24 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  25   $(function() { init_search(); });
  26 /* @license-end */
  27 </script>
  28 <script type="text/javascript" src="darkmode_toggle.js"></script>
  29 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  30 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  31 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  32 <link href="extra_tabs.css" rel="stylesheet" type="text/css"/>
  33 <link href="version.css" rel="stylesheet" type="text/css"/>
  34 <script type="text/javascript" src="../version.js"></script>
  35 </head>
  36 <body>
  37 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  38 <div id="titlearea">
  39 <table cellspacing="0" cellpadding="0">
  40  <tbody>
  41  <tr style="height: 55px;">
  42   <td id="projectlogo" style="padding: 1.5em;"><a href="https://www.keil.arm.com/cmsis" target="_blank"><img alt="Logo" src="cmsis_logo_white_small.png"/</a></td>
  43   <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
  44    <div id="projectname">CMSIS-FreeRTOS
  45    &#160;<span id="projectnumber"><script type="text/javascript">
  46      <!--
  47      writeHeader.call(this);
  48      writeVersionDropdown.call(this, "CMSIS-FreeRTOS");
  49      //-->
  50     </script>
  51    </span>
  52    </div>
  53    <div id="projectbrief">CMSIS-RTOS2 compliant FreeRTOS Implementation</div>
  54   </td>
  55    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
  56         <span class="left">
  57           <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
  58           <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
  59                onfocus="searchBox.OnSearchFieldFocus(true)"
  60                onblur="searchBox.OnSearchFieldFocus(false)"
  61                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  62           </span><span class="right">
  63             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
  64           </span>
  65         </div>
  66 </td>
  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 <!-- Generated by Doxygen 1.13.2 -->
  80 <script type="text/javascript">
  81 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  82 var searchBox = new SearchBox("searchBox", "search/",'.html');
  83 /* @license-end */
  84 </script>
  85 <script type="text/javascript">
  86 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  87 $(function() { codefold.init(0); });
  88 /* @license-end */
  89 </script>
  90 </div><!-- top -->
  91 <div id="side-nav" class="ui-resizable side-nav-resizable">
  92   <div id="nav-tree">
  93     <div id="nav-tree-contents">
  94       <div id="nav-sync" class="sync"></div>
  95     </div>
  96   </div>
  97   <div id="splitbar" style="-moz-user-select:none;"
  98        class="ui-resizable-handle">
  99   </div>
 100 </div>
 101 <script type="text/javascript">
 102 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 103 $(function(){initNavTree('page_create_project.html',''); initResizable(true); });
 104 /* @license-end */
 105 </script>
 106 <div id="doc-content">
 107 <!-- window showing the filter options -->
 108 <div id="MSearchSelectWindow"
 109      onmouseover="return searchBox.OnSearchSelectShow()"
 110      onmouseout="return searchBox.OnSearchSelectHide()"
 111      onkeydown="return searchBox.OnSearchSelectKey(event)">
 112 </div>
 113
 114 <!-- iframe showing the search results (closed by default) -->
 115 <div id="MSearchResultsWindow">
 116 <div id="MSearchResults">
 117 <div class="SRPage">
 118 <div id="SRIndex">
 119 <div id="SRResults"></div>
 120 <div class="SRStatus" id="Loading">Loading...</div>
 121 <div class="SRStatus" id="Searching">Searching...</div>
 122 <div class="SRStatus" id="NoMatches">No Matches</div>
 123 </div>
 124 </div>
 125 </div>
 126 </div>
 127
 128 <div><div class="header">
 129   <div class="headertitle"><div class="title">Create a FreeRTOS Project</div></div>
 130 </div><!--header-->
 131 <div class="contents">
 132 <div class="textblock"><p><a class="anchor" id="md_src_2create__project"></a></p>
 133 <p>You can basically choose between two options when creating a FreeRTOS project:</p>
 134 <ol type="1">
 135 <li><a class="el" href="#create_native_project">Using the FreeRTOS API and kernel</a>.</li>
 136 <li><a class="el" href="#create_cmsis_project">Using the CMSIS-RTOS2 API with an underlying FreeRTOS kernel</a>.</li>
 137 </ol>
 138 <p>Before starting, please review the brief summary of the <a class="el" href="#pack_components">Pack Components</a> below to familiarize yourself with them.</p>
 139 <h1><a class="anchor" id="pack_components"></a>
 140 Pack Components</h1>
 141 <p>The CMSIS-FreeRTOS pack includes the following components and their variants:</p>
 142 <table class="markdownTable">
 143 <tr class="markdownTableHead">
 144 <th class="markdownTableHeadNone">Component   </th><th class="markdownTableHeadNone">Variant   </th><th class="markdownTableHeadNone">Description    </th></tr>
 145 <tr class="markdownTableRowOdd">
 146 <td class="markdownTableBodyNone">CMSIS:RTOS2:FreeRTOS   </td><td class="markdownTableBodyNone">Cortex-M   </td><td class="markdownTableBodyNone">CMSIS-RTOS2 API implementation based on the FreeRTOS kernel for Cortex-M.    </td></tr>
 147 <tr class="markdownTableRowEven">
 148 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Cortex-A   </td><td class="markdownTableBodyNone">Adds support for external IRQ controller on Cortex-A processors.    </td></tr>
 149 <tr class="markdownTableRowOdd">
 150 <td class="markdownTableBodyNone">RTOS:CORE   </td><td class="markdownTableBodyNone">Cortex-M   </td><td class="markdownTableBodyNone">Core API for Cortex-M processors, providing task scheduling and communication.    </td></tr>
 151 <tr class="markdownTableRowEven">
 152 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Cortex-M MPU   </td><td class="markdownTableBodyNone">Adds support for the Memory Protection Unit (MPU) on Cortex-M processors.    </td></tr>
 153 <tr class="markdownTableRowOdd">
 154 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Cortex-M Non-Secure   </td><td class="markdownTableBodyNone">Core API for Cortex-M, supporting TrustZone non-secure domain operation. <b>[Warning: Deprecated]</b>    </td></tr>
 155 <tr class="markdownTableRowEven">
 156 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Cortex-M Non-Secure MPU   </td><td class="markdownTableBodyNone">Combines TrustZone non-secure domain support with MPU functionality. <b>[Warning: Deprecated]</b>    </td></tr>
 157 <tr class="markdownTableRowOdd">
 158 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Cortex-A   </td><td class="markdownTableBodyNone">Core API for Cortex-A processors.    </td></tr>
 159 <tr class="markdownTableRowEven">
 160 <td class="markdownTableBodyNone">RTOS:Config   </td><td class="markdownTableBodyNone">CMSIS RTOS2   </td><td class="markdownTableBodyNone">Configuration file tailored for the CMSIS-RTOS2 API.    </td></tr>
 161 <tr class="markdownTableRowOdd">
 162 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">FreeRTOS   </td><td class="markdownTableBodyNone">Configuration file for native FreeRTOS API usage.    </td></tr>
 163 <tr class="markdownTableRowEven">
 164 <td class="markdownTableBodyNone">RTOS:Coroutines   </td><td class="markdownTableBodyNone">-   </td><td class="markdownTableBodyNone">Adds FreeRTOS Co-routine API.    </td></tr>
 165 <tr class="markdownTableRowOdd">
 166 <td class="markdownTableBodyNone">RTOS:Event Groups   </td><td class="markdownTableBodyNone">-   </td><td class="markdownTableBodyNone">Provides event group functionality for task synchronization and communication.    </td></tr>
 167 <tr class="markdownTableRowEven">
 168 <td class="markdownTableBodyNone">RTOS:Heap   </td><td class="markdownTableBodyNone">Heap_1   </td><td class="markdownTableBodyNone">A simple memory allocation scheme that does not permit memory to be freed.    </td></tr>
 169 <tr class="markdownTableRowOdd">
 170 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Heap_2   </td><td class="markdownTableBodyNone">Allows memory to be freed but does not coalesce adjacent free memory blocks.    </td></tr>
 171 <tr class="markdownTableRowEven">
 172 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Heap_3   </td><td class="markdownTableBodyNone">Wraps the standard <code>malloc()</code> and <code>free()</code> functions for thread safety.    </td></tr>
 173 <tr class="markdownTableRowOdd">
 174 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Heap_4   </td><td class="markdownTableBodyNone">Coalesces adjacent free memory blocks to avoid fragmentation.    </td></tr>
 175 <tr class="markdownTableRowEven">
 176 <td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone">Heap_5   </td><td class="markdownTableBodyNone">Extends Heap_4 with the ability to span the heap across non-adjacent memory areas.    </td></tr>
 177 <tr class="markdownTableRowOdd">
 178 <td class="markdownTableBodyNone">RTOS:Message Buffer   </td><td class="markdownTableBodyNone">-   </td><td class="markdownTableBodyNone">Enables tasks and interrupts to send and receive variable-length messages.    </td></tr>
 179 <tr class="markdownTableRowEven">
 180 <td class="markdownTableBodyNone">RTOS:Stream Buffer   </td><td class="markdownTableBodyNone">-   </td><td class="markdownTableBodyNone">Allows tasks and interrupts to send and receive continuous streams of data.    </td></tr>
 181 <tr class="markdownTableRowOdd">
 182 <td class="markdownTableBodyNone">RTOS:Timers   </td><td class="markdownTableBodyNone">-   </td><td class="markdownTableBodyNone">Adds support for software timers, enabling delayed and periodic function execution.    </td></tr>
 183 <tr class="markdownTableRowEven">
 184 <td class="markdownTableBodyNone">RTOS:TrustZone   </td><td class="markdownTableBodyNone">-   </td><td class="markdownTableBodyNone">Provides context management for execution in TrustZone secure domain.   </td></tr>
 185 </table>
 186 <blockquote class="doxtable">
 187 <p><b>NOTE</b></p>
 188 <p>CMSIS-FreeRTOS 11.2.0 adds support for TrustZone <b>domain detection from project</b> settings. Regardless of the build contexts (no TrustZone, TrustZone secure or non-secure domain) the below variants shall be used:</p>
 189 <ul>
 190 <li>RTOS:CORE&amp;Cortex-M</li>
 191 <li>RTOS:CORE&amp;Cortex-M MPU</li>
 192 </ul>
 193 <p>This makes <b>variants Cortex-M Non-Secure and Cortex-M Non-Secure MPU obsolete</b> and will be removed in future releases. </p>
 194 </blockquote>
 195 <h1><a class="anchor" id="create_native_project"></a>
 196 Create a Native FreeRTOS Project</h1>
 197 <p>The steps to create a microcontroller application using FreeRTOS are:</p>
 198 <ul>
 199 <li>Create a new project and select a microcontroller device.</li>
 200 <li>In the Manage Run-Time Environment window, select <b>::Device:Startup</b>, <b>::RTOS:CORE</b> and <b>::RTOS:Config</b> in the <b>FreeRTOS</b> variant and an applicable <b>::RTOS:Heap</b> scheme (for more information on the heap schemes, visit the FreeRTOS documentation):</li>
 201 </ul>
 202 <div class="image">
 203 <img src="manage_rte_freertos_native.png" alt=""/>
 204 <div class="caption">
 205 Manage RTE FreeRTOS Native</div></div>
 206     <p><br  />
 207 </p><ul>
 208 <li>If the <b>Validation Output</b> requires other components to be present, try to use the <b>Resolve</b> button.</li>
 209 <li>Click <b>OK</b>. In the <b>Project</b> window, you will see the files that have been automatically added to your project, such as <b>FreeRTOSConfig.h</b>, the source code files, as well as the system and startup files:</li>
 210 </ul>
 211 <div class="image">
 212 <img src="project_window_freertos_native.png" alt=""/>
 213 <div class="caption">
 214 Project Window FreeRTOS Native</div></div>
 215     <h2><a class="anchor" id="configure_native_freertos"></a>
 216 Configure FreeRTOS</h2>
 217 <p>When you have created the native FreeRTOS project, you can configure the real-time operating system using the <b>FreeRTOSConfig.h</b> file. Please refer to the <a href="https://www.freertos.org/a00110.html">FreeRTOS documentation</a> for more information on the specific settings.</p>
 218 <div class="image">
 219 <img src="freertos_config_h_native.png" alt=""/>
 220 <div class="caption">
 221 FreeRTOS Config H Native</div></div>
 222     <h2><a class="anchor" id="interrupt_priority_config"></a>
 223 Interrupt Priority Configuration</h2>
 224 <p>FreeRTOS implements critical sections using the <a href="https://developer.arm.com/documentation/dui0552/a/the-cortex-m3-processor/programmers-model/core-registers?lang=en">BASEPRI</a> register (available in Armv7-M and Armv8-M architecture-based devices) which masks only a subset of interrupts. This is configured via the <code>configMAX_SYSCALL_INTERRUPT_PRIORITY</code> setting. Therefore, it is needed to properly configure this setting. It is also needed to set appropriate interrupt priorities for interrupt service routines (ISR) that use RTOS functions. This can especially impact drivers which typically use peripheral interrupts. Normally, these use the RTOS directly or indirectly through registered callbacks.</p>
 225 <p>Arm Cortex-M cores store interrupt priority values in the most significant bits of the interrupt priority registers which can have a maximum of eight bits. Many implementations offer only three priority bits. These three bits are shifted up to be bits five, six and seven respectively. <code>configMAX_SYSCALL_INTERRUPT_PRIORITY</code> must not be 0 and can be xxx00000. This results in the following table:</p>
 226 <table class="markdownTable">
 227 <tr class="markdownTableHead">
 228 <th class="markdownTableHeadCenter">configMAX_SYSCALL_INTERRUPT_PRIORITY   </th><th class="markdownTableHeadCenter">Upper three bits   </th><th class="markdownTableHeadCenter">Priority    </th></tr>
 229 <tr class="markdownTableRowOdd">
 230 <td class="markdownTableBodyCenter">32   </td><td class="markdownTableBodyCenter">001   </td><td class="markdownTableBodyCenter">1 (Highest)    </td></tr>
 231 <tr class="markdownTableRowEven">
 232 <td class="markdownTableBodyCenter">64   </td><td class="markdownTableBodyCenter">010   </td><td class="markdownTableBodyCenter">2    </td></tr>
 233 <tr class="markdownTableRowOdd">
 234 <td class="markdownTableBodyCenter">96   </td><td class="markdownTableBodyCenter">011   </td><td class="markdownTableBodyCenter">3    </td></tr>
 235 <tr class="markdownTableRowEven">
 236 <td class="markdownTableBodyCenter">128   </td><td class="markdownTableBodyCenter">100   </td><td class="markdownTableBodyCenter">4    </td></tr>
 237 <tr class="markdownTableRowOdd">
 238 <td class="markdownTableBodyCenter">160   </td><td class="markdownTableBodyCenter">101   </td><td class="markdownTableBodyCenter">5    </td></tr>
 239 <tr class="markdownTableRowEven">
 240 <td class="markdownTableBodyCenter">196   </td><td class="markdownTableBodyCenter">110   </td><td class="markdownTableBodyCenter">6    </td></tr>
 241 <tr class="markdownTableRowOdd">
 242 <td class="markdownTableBodyCenter">224   </td><td class="markdownTableBodyCenter">111   </td><td class="markdownTableBodyCenter">7 (Lowest)   </td></tr>
 243 </table>
 244 <h3>Example</h3>
 245 <p>If you set <code>configMAX_SYSCALL_INTERRUPT_PRIORITY</code> to 32, then the priority of an interrupt service routine that uses RTOS functions must then be higher or equal to 1. This ensures that this interrupt will be masked during a critical section.</p>
 246 <p>A WiFi driver using the SPI interface registers a callback to SPI which is executed in an interrupt context. The callback function in the WiFi driver uses RTOS functions. Therefore, the SPI interrupt priority must be set to a value equal or higher to the FreeRTOS preempt priority, for example 1.</p>
 247 <blockquote class="doxtable">
 248 <p><b>Note:</b></p>
 249 <ul>
 250 <li>For a detailed description of how FreeRTOS is using Cortex-M code registers, refer to <a href="https://www.freertos.org/RTOS-Cortex-M3-M4.html">Running the RTOS on an ARM Cortex-M Core</a>. </li>
 251 </ul>
 252 </blockquote>
 253 <h2><a class="anchor" id="native_freertos_add_evr"></a>
 254 Add Event Recorder Visibility</h2>
 255 <ul>
 256 <li>To use the Event Recorder together with FreeRTOS, add the software component <b>::Compiler:Event Recorder</b> to your project.</li>
 257 <li>Open <a class="el" href="#configure_native_freertos">FreeRTOSConfig.h</a> and<ul>
 258 <li>verify the header file <b>freertos_evr.h</b> is included</li>
 259 <li>add Event Recorder configuration definitions (see <a class="el" href="#configure_evr">Event Recorder Configuration</a>)</li>
 260 </ul>
 261 </li>
 262 <li>Call <b><a class="el" href="group__freertos__setup.html#ga943f40b05c79f40c73d67b1adcbe3dbe" title="Setup Event Recorder configuration.">EvrFreeRTOSSetup()</a></b> in your application code (ideally in <code>main()</code>).</li>
 263 <li>If you are using simulation mode, add an initialization file with the following content: <div class="fragment"><div class="line">MAP 0xE0001000, 0xE0001007 READ WRITE</div>
 264 <div class="line">signal void DWT_CYCCNT (void) {</div>
 265 <div class="line">while (1) {</div>
 266 <div class="line">  rwatch(0xE0001004);</div>
 267 <div class="line">  _WWORD(0xE0001004, states);</div>
 268 <div class="line">  }</div>
 269 <div class="line">}</div>
 270 <div class="line">DWT_CYCCNT()</div>
 271 </div><!-- fragment --></li>
 272 <li>Build the application code and download it to the debug hardware or run it in simulation.</li>
 273 </ul>
 274 <p>Once the target application generates event information, it can be viewed in the µVision debugger using the <b>Event Recorder</b>.</p>
 275 <h1><a class="anchor" id="create_cmsis_project"></a>
 276 Create a CMSIS-FreeRTOS Project</h1>
 277 <p>The steps to create a microcontroller application using CMSIS-FreeRTOS are:</p>
 278 <ul>
 279 <li>Create a new project and select a microcontroller device.</li>
 280 <li>In the Manage Run-Time Environment window, select <b>::Device:Startup</b>, <b>::CMSIS::RTOS2 (API)::FreeRTOS</b>, <b>::RTOS:CORE</b> in the <b>FreeRTOS</b> variant, <b>::RTOS:Config</b> in the <b>CMSIS RTOS2</b> variant, <b>::RTOS:Timers</b>, <b>::RTOS:Event Groups</b>, and an applicable <b>::RTOS:Heap</b> scheme (for more information on the heap schemes, visit the FreeRTOS documentation):</li>
 281 </ul>
 282 <div class="image">
 283 <img src="manage_rte_freertos_rtos2.png" alt=""/>
 284 <div class="caption">
 285 Manage RTE FreeRTOS RTOS2</div></div>
 286     <p><br  />
 287 </p><ul>
 288 <li>If the <b>Validation Output</b> requires other components to be present, try to use the <b>Resolve</b> button.</li>
 289 <li>Click <b>OK</b>. In the <b>Project</b> window, you will see the files that have been automatically added to your project, such as <b>FreeRTOSConfig.h</b>, the source code files, as well as the system and startup files:</li>
 290 </ul>
 291 <div class="image">
 292 <img src="project_window_freertos_rtos2.png" alt=""/>
 293 <div class="caption">
 294 Project Window FreeRTOS RTOS2</div></div>
 295     <h2><a class="anchor" id="configure_cmsis_freertos"></a>
 296 Configure CMSIS-FreeRTOS</h2>
 297 <p>When you have created the CMSIS-FreeRTOS project, you can configure the real-time operating system using the <b>FreeRTOSConfig.h</b> file. It can be opened using the Configuration Wizard view:</p>
 298 <div class="image">
 299 <img src="freertos_config_h_cmsis_rtos.png" alt=""/>
 300 <div class="caption">
 301 FreeRTOS Config H CMSIS RTOS</div></div>
 302     <p>The following main settings are available:</p>
 303 <table class="markdownTable">
 304 <tr class="markdownTableHead">
 305 <th class="markdownTableHeadNone">Name   </th><th class="markdownTableHeadNone">Configuration define   </th><th class="markdownTableHeadNone">Description    </th></tr>
 306 <tr class="markdownTableRowOdd">
 307 <td class="markdownTableBodyNone">Minimal stack size [words]   </td><td class="markdownTableBodyNone">configMINIMAL_STACK_SIZE   </td><td class="markdownTableBodyNone">Stack for idle task and default task stack in words.    </td></tr>
 308 <tr class="markdownTableRowEven">
 309 <td class="markdownTableBodyNone">Total heap size [bytes]   </td><td class="markdownTableBodyNone">configTOTAL_HEAP_SIZE   </td><td class="markdownTableBodyNone">Heap memory size in bytes.    </td></tr>
 310 <tr class="markdownTableRowOdd">
 311 <td class="markdownTableBodyNone">Kernel tick frequency [Hz]   </td><td class="markdownTableBodyNone">configTICK_RATE_HZ   </td><td class="markdownTableBodyNone">Kernel tick rate in Hz.    </td></tr>
 312 <tr class="markdownTableRowEven">
 313 <td class="markdownTableBodyNone">Timer task stack depth [words]   </td><td class="markdownTableBodyNone">configTIMER_TASK_STACK_DEPTH   </td><td class="markdownTableBodyNone">Stack for timer task in words.    </td></tr>
 314 <tr class="markdownTableRowOdd">
 315 <td class="markdownTableBodyNone">Timer task priority   </td><td class="markdownTableBodyNone">configTIMER_TASK_PRIORITY   </td><td class="markdownTableBodyNone">Timer task priority.    </td></tr>
 316 <tr class="markdownTableRowEven">
 317 <td class="markdownTableBodyNone">Timer queue length   </td><td class="markdownTableBodyNone">configTIMER_QUEUE_LENGTH   </td><td class="markdownTableBodyNone">Timer command queue length.    </td></tr>
 318 <tr class="markdownTableRowOdd">
 319 <td class="markdownTableBodyNone">Preemption interrupt priority   </td><td class="markdownTableBodyNone">configMAX_SYSCALL_INTERRUPT_PRIORITY   </td><td class="markdownTableBodyNone">Maximum priority of interrupts that are safe to call FreeRTOS API.    </td></tr>
 320 <tr class="markdownTableRowEven">
 321 <td class="markdownTableBodyNone">Use time slicing   </td><td class="markdownTableBodyNone">configUSE_TIME_SLICING   </td><td class="markdownTableBodyNone">Enable setting to use time slicing.    </td></tr>
 322 <tr class="markdownTableRowOdd">
 323 <td class="markdownTableBodyNone">Use tickless idle   </td><td class="markdownTableBodyNone">configUSE_TICKLESS_IDLE   </td><td class="markdownTableBodyNone">Enable low power tickless mode that stops tick interrupt when idle.    </td></tr>
 324 <tr class="markdownTableRowEven">
 325 <td class="markdownTableBodyNone">Idle should yield   </td><td class="markdownTableBodyNone">configIDLE_SHOULD_YIELD   </td><td class="markdownTableBodyNone">Control Yield behavior of the idle task.    </td></tr>
 326 <tr class="markdownTableRowOdd">
 327 <td class="markdownTableBodyNone">Check for stack overflow   </td><td class="markdownTableBodyNone">configCHECK_FOR_STACK_OVERFLOW   </td><td class="markdownTableBodyNone">Enable or disable stack overflow checking.    </td></tr>
 328 <tr class="markdownTableRowEven">
 329 <td class="markdownTableBodyNone">Use idle hook   </td><td class="markdownTableBodyNone">configUSE_IDLE_HOOK   </td><td class="markdownTableBodyNone">Enable callback function call on each idle task iteration.    </td></tr>
 330 <tr class="markdownTableRowOdd">
 331 <td class="markdownTableBodyNone">Use tick hook   </td><td class="markdownTableBodyNone">configUSE_TICK_HOOK   </td><td class="markdownTableBodyNone">Enable callback function call during each tick interrupt.    </td></tr>
 332 <tr class="markdownTableRowEven">
 333 <td class="markdownTableBodyNone">Use daemon task startup hook   </td><td class="markdownTableBodyNone">configUSE_DAEMON_TASK_STARTUP_HOOK   </td><td class="markdownTableBodyNone">Enable callback function call when timer service starts.    </td></tr>
 334 <tr class="markdownTableRowOdd">
 335 <td class="markdownTableBodyNone">Use malloc failed hook   </td><td class="markdownTableBodyNone">configUSE_MALLOC_FAILED_HOOK   </td><td class="markdownTableBodyNone">Enable callback function call when out of dynamic memory.    </td></tr>
 336 <tr class="markdownTableRowEven">
 337 <td class="markdownTableBodyNone">Queue registry size   </td><td class="markdownTableBodyNone">configQUEUE_REGISTRY_SIZE   </td><td class="markdownTableBodyNone">Define maximum number of queue objects registered for debug purposes.   </td></tr>
 338 </table>
 339 <blockquote class="doxtable">
 340 <p><b>Note</b></p>
 341 <ul>
 342 <li>Refer to <a class="el" href="#interrupt_priority_config">Interrupt Priority Configuration</a> for more information on the usage of <code>configMAX_SYSCALL_INTERRUPT_PRIORITY</code>. </li>
 343 </ul>
 344 </blockquote>
 345 <h3>Event Recorder Configuration</h3>
 346 <p>The following settings are available (see <a class="el" href="#configure_evr">Event Recorder Configuration</a> for details):</p>
 347 <table class="markdownTable">
 348 <tr class="markdownTableHead">
 349 <th class="markdownTableHeadNone">Name   </th><th class="markdownTableHeadNone">Configuration define   </th><th class="markdownTableHeadNone">Description    </th></tr>
 350 <tr class="markdownTableRowOdd">
 351 <td class="markdownTableBodyNone">Initialize Event Recorder   </td><td class="markdownTableBodyNone">configEVR_INITIALIZE   </td><td class="markdownTableBodyNone">Initialize Event Recorder before FreeRTOS kernel start.    </td></tr>
 352 <tr class="markdownTableRowEven">
 353 <td class="markdownTableBodyNone">Setup recording level filter   </td><td class="markdownTableBodyNone">configEVR_SETUP_LEVEL   </td><td class="markdownTableBodyNone">Enable configuration of FreeRTOS events recording level.    </td></tr>
 354 <tr class="markdownTableRowOdd">
 355 <td class="markdownTableBodyNone">Task functions   </td><td class="markdownTableBodyNone">configEVR_LEVEL_TASKS   </td><td class="markdownTableBodyNone">Define event recording level bitmask for events generated from Tasks functions.    </td></tr>
 356 <tr class="markdownTableRowEven">
 357 <td class="markdownTableBodyNone">Queue functions   </td><td class="markdownTableBodyNone">configEVR_LEVEL_QUEUE   </td><td class="markdownTableBodyNone">Define event recording level bitmask for events generated from Queue functions.    </td></tr>
 358 <tr class="markdownTableRowOdd">
 359 <td class="markdownTableBodyNone">Timer functions   </td><td class="markdownTableBodyNone">configEVR_LEVEL_TIMERS   </td><td class="markdownTableBodyNone">Define event recording level bitmask for events generated from Timer functions.    </td></tr>
 360 <tr class="markdownTableRowEven">
 361 <td class="markdownTableBodyNone">Event Groups functions   </td><td class="markdownTableBodyNone">configEVR_LEVEL_EVENTGROUPS   </td><td class="markdownTableBodyNone">Define event recording level bitmask for events generated from Event Groups functions.    </td></tr>
 362 <tr class="markdownTableRowOdd">
 363 <td class="markdownTableBodyNone">Heap functions   </td><td class="markdownTableBodyNone">configEVR_LEVEL_HEAP   </td><td class="markdownTableBodyNone">Define event recording level bitmask for events generated from Heap functions.    </td></tr>
 364 <tr class="markdownTableRowEven">
 365 <td class="markdownTableBodyNone">Stream Buffer functions   </td><td class="markdownTableBodyNone">configEVR_LEVEL_STREAMBUFFER   </td><td class="markdownTableBodyNone">Define event recording level bitmask for events generated from Stream Buffer functions.   </td></tr>
 366 </table>
 367 <h3>Memory Allocation Configuration</h3>
 368 <p>The following settings are available:</p>
 369 <table class="markdownTable">
 370 <tr class="markdownTableHead">
 371 <th class="markdownTableHeadNone">Name   </th><th class="markdownTableHeadNone">Configuration define   </th><th class="markdownTableHeadNone">Description    </th></tr>
 372 <tr class="markdownTableRowOdd">
 373 <td class="markdownTableBodyNone">Support static memory allocation   </td><td class="markdownTableBodyNone">configSUPPORT_STATIC_ALLOCATION   </td><td class="markdownTableBodyNone">Enable or disable support for static memory allocation.    </td></tr>
 374 <tr class="markdownTableRowEven">
 375 <td class="markdownTableBodyNone">Support dynamic memory allocation   </td><td class="markdownTableBodyNone">configSUPPORT_DYNAMIC_ALLOCATION   </td><td class="markdownTableBodyNone">Enable or disable support for dynamic memory allocation.    </td></tr>
 376 <tr class="markdownTableRowOdd">
 377 <td class="markdownTableBodyNone">Use kernel provided static memory   </td><td class="markdownTableBodyNone">configKERNEL_PROVIDED_STATIC_MEMORY   </td><td class="markdownTableBodyNone">When enabled, FreeRTOS kernel provides static memory for Idle and Timer tasks.    </td></tr>
 378 <tr class="markdownTableRowEven">
 379 <td class="markdownTableBodyNone">Use application allocated heap   </td><td class="markdownTableBodyNone">configAPPLICATION_ALLOCATED_HEAP   </td><td class="markdownTableBodyNone">When enabled, application must provide heap buffer externally.    </td></tr>
 380 <tr class="markdownTableRowOdd">
 381 <td class="markdownTableBodyNone">Use separate heap for stack allocation   </td><td class="markdownTableBodyNone">configSTACK_ALLOCATION_FROM_SEPARATE_HEAP   </td><td class="markdownTableBodyNone">Enable or disable stack allocation for any task from a separate heap.    </td></tr>
 382 <tr class="markdownTableRowEven">
 383 <td class="markdownTableBodyNone">Use heap protector   </td><td class="markdownTableBodyNone">configENABLE_HEAP_PROTECTOR   </td><td class="markdownTableBodyNone">Enable or disable bounds checking and obfuscation to heap block pointers.   </td></tr>
 384 </table>
 385 <h3>Port Specific Configuration</h3>
 386 <p>The following settings are available:</p>
 387 <table class="markdownTable">
 388 <tr class="markdownTableHead">
 389 <th class="markdownTableHeadNone">Name   </th><th class="markdownTableHeadNone">Configuration define   </th><th class="markdownTableHeadNone">Description    </th></tr>
 390 <tr class="markdownTableRowOdd">
 391 <td class="markdownTableBodyNone">Use Floating Point Unit   </td><td class="markdownTableBodyNone">configENABLE_FPU   </td><td class="markdownTableBodyNone">Enable or disable support for FPU when switching execution context.    </td></tr>
 392 <tr class="markdownTableRowEven">
 393 <td class="markdownTableBodyNone">Use M-Profile Vector Extension   </td><td class="markdownTableBodyNone">configENABLE_MVE   </td><td class="markdownTableBodyNone">Enable or disable support for MVE when switching execution context.    </td></tr>
 394 <tr class="markdownTableRowOdd">
 395 <td class="markdownTableBodyNone">Use Memory Protection Unit   </td><td class="markdownTableBodyNone">configENABLE_MPU   </td><td class="markdownTableBodyNone">Enable or disable support for MPU on ARMv8-M MPU enabled ports.    </td></tr>
 396 <tr class="markdownTableRowEven">
 397 <td class="markdownTableBodyNone">Use TrustZone Secure Side Only   </td><td class="markdownTableBodyNone">configRUN_FREERTOS_SECURE_ONLY   </td><td class="markdownTableBodyNone">Enable this setting when FreeRTOS runs on the Secure side only.    </td></tr>
 398 <tr class="markdownTableRowOdd">
 399 <td class="markdownTableBodyNone">Use TrustZone Security Extension   </td><td class="markdownTableBodyNone">configENABLE_TRUSTZONE   </td><td class="markdownTableBodyNone">Enable TrustZone when FreeRTOS runs on the Non-Secure side and calls functions from the Secure side.    </td></tr>
 400 <tr class="markdownTableRowEven">
 401 <td class="markdownTableBodyNone">Minimal secure stack size [words]   </td><td class="markdownTableBodyNone">configMINIMAL_SECURE_STACK_SIZE   </td><td class="markdownTableBodyNone">Stack for idle task Secure side context in words.   </td></tr>
 402 </table>
 403 <h3>Interrupt Controller Configuration</h3>
 404 <p><b>Note:</b> Settings related to interrupt controller are relevant only on ARMv7-A ports where it is necessary to configure Arm Generic Interrupt Controller (GIC).</p>
 405 <p>The following settings are available:</p>
 406 <table class="markdownTable">
 407 <tr class="markdownTableHead">
 408 <th class="markdownTableHeadNone">Name   </th><th class="markdownTableHeadNone">Configuration define   </th><th class="markdownTableHeadNone">Description    </th></tr>
 409 <tr class="markdownTableRowOdd">
 410 <td class="markdownTableBodyNone">Interrupt controller base address   </td><td class="markdownTableBodyNone">configINTERRUPT_CONTROLLER_BASE_ADDRESS   </td><td class="markdownTableBodyNone">Sets the base address of the interrupt controller peripheral.    </td></tr>
 411 <tr class="markdownTableRowEven">
 412 <td class="markdownTableBodyNone">Interrupt controller CPU interface offset   </td><td class="markdownTableBodyNone">configINTERRUPT_CONTROLLER_CPU_INTERFACE_OFFSET   </td><td class="markdownTableBodyNone">Sets the offset from interrupt controller base address at which the CPU interface starts.    </td></tr>
 413 <tr class="markdownTableRowOdd">
 414 <td class="markdownTableBodyNone">Interrupt controller unique priorities   </td><td class="markdownTableBodyNone">configUNIQUE_INTERRUPT_PRIORITIES   </td><td class="markdownTableBodyNone">Sets the number of unique priorities that can be specified in the interrupt controller peripheral.   </td></tr>
 415 </table>
 416 <h3>Symmetric Multiprocessing Configuration</h3>
 417 <p><b>Note:</b> Symmetric Multiprocessing Configuration (SMP) settings are only relevant if FreeRTOS port implementation supports SMP.</p>
 418 <p>The following settings are available:</p>
 419 <table class="markdownTable">
 420 <tr class="markdownTableHead">
 421 <th class="markdownTableHeadNone">Name   </th><th class="markdownTableHeadNone">Configuration define   </th><th class="markdownTableHeadNone">Description    </th></tr>
 422 <tr class="markdownTableRowOdd">
 423 <td class="markdownTableBodyNone">Number of processor cores   </td><td class="markdownTableBodyNone">configNUMBER_OF_CORES   </td><td class="markdownTableBodyNone">Sets the number of available processor cores.    </td></tr>
 424 <tr class="markdownTableRowEven">
 425 <td class="markdownTableBodyNone">Use processor core affinity   </td><td class="markdownTableBodyNone">configUSE_CORE_AFFINITY   </td><td class="markdownTableBodyNone">Enables the control for task to run on specific processor cores.    </td></tr>
 426 <tr class="markdownTableRowOdd">
 427 <td class="markdownTableBodyNone">Use passive idle hook   </td><td class="markdownTableBodyNone">configUSE_PASSIVE_IDLE_HOOK   </td><td class="markdownTableBodyNone">Enable callback function call on each idle task iteration.   </td></tr>
 428 </table>
 429 <h2><a class="anchor" id="cmsis_freertos_add_evr"></a>
 430 Add Event Recorder Visibility</h2>
 431 <ul>
 432 <li>To use the Event Recorder together with FreeRTOS, add the software component <b>::Compiler:Event Recorder</b> to your project.</li>
 433 <li>Open <a class="el" href="#configure_cmsis_freertos">FreeRTOSConfig.h</a> and<ul>
 434 <li>verify the header file <b>freertos_evr.h</b> is included</li>
 435 <li>modify Event Recorder configuration definitions (see <a class="el" href="#configure_evr">Event Recorder Configuration</a>) to change default configuration</li>
 436 </ul>
 437 </li>
 438 <li>Call <b>osKernelInitialize()</b> in your application code (ideally in <code>main()</code>) to setup Event Recorder according to configuration settings.</li>
 439 <li>If you are using simulation mode, add an initialization file with the following content: <div class="fragment"><div class="line">MAP 0xE0001000, 0xE0001007 READ WRITE</div>
 440 <div class="line">signal void DWT_CYCCNT (void) {</div>
 441 <div class="line">while (1) {</div>
 442 <div class="line">  rwatch(0xE0001004);</div>
 443 <div class="line">  _WWORD(0xE0001004, states);</div>
 444 <div class="line">  }</div>
 445 <div class="line">}</div>
 446 <div class="line">DWT_CYCCNT()</div>
 447 </div><!-- fragment --></li>
 448 <li>Build the application code and download it to the debug hardware or run it in simulation.</li>
 449 </ul>
 450 <p>Once the target application generates event information, it can be viewed in the µVision debugger using the <b>Event Recorder</b>.</p>
 451 <h1><a class="anchor" id="create_mixed_project"></a>
 452 Create a Mixed-Interface Project</h1>
 453 <p>Using CMSIS-RTOS2 API and native FreeRTOS API simultaneously is possible and some projects do require using the native FreeRTOS API and the CMSIS-RTOS2 API at the same time. Such project should be <a class="el" href="#create_cmsis_project">created as CMSIS-FreeRTOS project</a>.</p>
 454 <p>Depending on the application requirements, FreeRTOS kernel can be started either by using FreeRTOS native API or by using CMSIS-RTOS2 API.</p>
 455 <h2><a class="anchor" id="autotoc_md2"></a>
 456 Start the Kernel Using CMSIS-RTOS2 API</h2>
 457 <div class="fragment"><div class="line"><span class="comment">/*</span></div>
 458 <div class="line"><span class="comment">  Application thread: Initialize and start the Application</span></div>
 459 <div class="line"><span class="comment">*/</span></div>
 460 <div class="line"><span class="keywordtype">void</span> app_main (<span class="keywordtype">void</span> *argument) {</div>
 461 <div class="line"> </div>
 462 <div class="line">  <span class="keywordflow">while</span>(1) {</div>
 463 <div class="line">    <span class="comment">// Application code</span></div>
 464 <div class="line">    <span class="comment">// ...</span></div>
 465 <div class="line">  }</div>
 466 <div class="line">}</div>
 467 <div class="line"> </div>
 468 <div class="line"><span class="comment">/*</span></div>
 469 <div class="line"><span class="comment">  Main function: Initialize and start the kernel</span></div>
 470 <div class="line"><span class="comment">*/</span></div>
 471 <div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
 472 <div class="line">  SystemCoreClockUpdate();</div>
 473 <div class="line"> </div>
 474 <div class="line">  <span class="comment">// Initialize CMSIS-RTOS2</span></div>
 475 <div class="line">  osKernelInitialize();</div>
 476 <div class="line"> </div>
 477 <div class="line">  <span class="comment">// Create application main thread</span></div>
 478 <div class="line">  osThreadNew(app_main, NULL, NULL);</div>
 479 <div class="line"> </div>
 480 <div class="line">  <span class="comment">// Start the kernel and execute the first thread</span></div>
 481 <div class="line">  osKernelStart();</div>
 482 <div class="line"> </div>
 483 <div class="line">  <span class="keywordflow">while</span>(1);</div>
 484 <div class="line">}</div>
 485 </div><!-- fragment --><h3>Restrictions</h3>
 486 <p>After the kernel is started using CMSIS-RTOS2 API, FreeRTOS native API can be used with the following restrictions:</p>
 487 <ul>
 488 <li><code>vTaskStartScheduler</code> must not be called</li>
 489 </ul>
 490 <h2><a class="anchor" id="autotoc_md3"></a>
 491 Start the Kernel Using Native API</h2>
 492 <div class="fragment"><div class="line"><span class="comment">/*</span></div>
 493 <div class="line"><span class="comment">  Application main thread: Initialize and start the application</span></div>
 494 <div class="line"><span class="comment">*/</span></div>
 495 <div class="line"><span class="keywordtype">void</span> app_main (<span class="keywordtype">void</span> *argument) {</div>
 496 <div class="line"> </div>
 497 <div class="line">  <span class="keywordflow">while</span>(1) {</div>
 498 <div class="line">    <span class="comment">// Application code</span></div>
 499 <div class="line">    <span class="comment">// ...</span></div>
 500 <div class="line">  }</div>
 501 <div class="line">}</div>
 502 <div class="line"> </div>
 503 <div class="line"><span class="comment">/*</span></div>
 504 <div class="line"><span class="comment">  Main function: Initialize and start the kernel</span></div>
 505 <div class="line"><span class="comment">*/</span></div>
 506 <div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
 507 <div class="line">  SystemCoreClockUpdate();</div>
 508 <div class="line"> </div>
 509 <div class="line">  <span class="comment">// Setup the Event Recorder (optionally)</span></div>
 510 <div class="line">  <a class="code hl_function" href="group__freertos__setup.html#ga943f40b05c79f40c73d67b1adcbe3dbe" title="Setup Event Recorder configuration.">EvrFreeRTOSSetup</a>(0);</div>
 511 <div class="line"> </div>
 512 <div class="line">  <span class="comment">// Create application main thread</span></div>
 513 <div class="line">  xTaskCreate (app_main, <span class="stringliteral">&quot;app_main&quot;</span>, 64, NULL, tskIDLE_PRIORITY+1, NULL);</div>
 514 <div class="line"> </div>
 515 <div class="line">  <span class="comment">// Start the kernel and execute the first thread</span></div>
 516 <div class="line">  vTaskStartScheduler();</div>
 517 <div class="line"> </div>
 518 <div class="line">  <span class="keywordflow">while</span>(1);</div>
 519 <div class="line">}</div>
 520 </div><!-- fragment --><h3>Restrictions</h3>
 521 <p>After the kernel is started using FreeRTOS native API, CMSIS-RTOS2 API can be used without restrictions.</p>
 522 <h1><a class="anchor" id="configure_evr"></a>
 523 Configure Event Recorder</h1>
 524 <p>This section describes the configuration settings for the <a href="https://arm-software.github.io/CMSIS-View/latest/evr.html">Event Recorder</a>. For more information refer to section <a class="el" href="#native_freertos_add_evr">Add Event Recorder Visibility to native FreeRTOS project</a> or <a class="el" href="#cmsis_freertos_add_evr">Add Event Recorder Visibility to CMSIS-FreeRTOS project</a>.</p>
 525 <p>Use below definitions to configure Event Recorder initialization and recording level filter setup.</p>
 526 <div class="fragment"><div class="line">#define configEVR_INITIALIZE</div>
 527 </div><!-- fragment --><table class="markdownTable">
 528 <tr class="markdownTableHead">
 529 <th class="markdownTableHeadNone">Value   </th><th class="markdownTableHeadNone">Description    </th></tr>
 530 <tr class="markdownTableRowOdd">
 531 <td class="markdownTableBodyNone">0   </td><td class="markdownTableBodyNone">Disable Event Recorder initialization    </td></tr>
 532 <tr class="markdownTableRowEven">
 533 <td class="markdownTableBodyNone">1   </td><td class="markdownTableBodyNone">Enable Event Recorder initialization   </td></tr>
 534 </table>
 535 <p>Definition <code>configEVR_INITIALIZE</code> enables Event Recorder initialization during execution of function <code>EvrFreeRTOSSetup</code>. Default value is <code>1</code>.</p>
 536 <div class="fragment"><div class="line">#define configEVR_SETUP_LEVEL</div>
 537 </div><!-- fragment --><table class="markdownTable">
 538 <tr class="markdownTableHead">
 539 <th class="markdownTableHeadNone">Value   </th><th class="markdownTableHeadNone">Description    </th></tr>
 540 <tr class="markdownTableRowOdd">
 541 <td class="markdownTableBodyNone">0   </td><td class="markdownTableBodyNone">Disable recording level filter setup    </td></tr>
 542 <tr class="markdownTableRowEven">
 543 <td class="markdownTableBodyNone">1   </td><td class="markdownTableBodyNone">Enable recording level filter setup   </td></tr>
 544 </table>
 545 <p>Definition <code>configEVR_SETUP_LEVEL</code> enables setup of recording level filter for events generated by FreeRTOS. Recording level is configured during execution of function <code>EvrFreeRTOSSetup</code>. Default value is <code>1</code>.</p>
 546 <div class="fragment"><div class="line">#define configEVR_LEVEL_TASKS</div>
 547 <div class="line">#define configEVR_LEVEL_QUEUE</div>
 548 <div class="line">#define configEVR_LEVEL_TIMERS</div>
 549 <div class="line">#define configEVR_LEVEL_EVENTGROUPS</div>
 550 <div class="line">#define configEVR_LEVEL_HEAP</div>
 551 <div class="line">#define configEVR_LEVEL_STREAMBUFFER</div>
 552 </div><!-- fragment --><table class="markdownTable">
 553 <tr class="markdownTableHead">
 554 <th class="markdownTableHeadNone">Value   </th><th class="markdownTableHeadNone">Description    </th></tr>
 555 <tr class="markdownTableRowOdd">
 556 <td class="markdownTableBodyNone">0x00   </td><td class="markdownTableBodyNone">Disable event generation    </td></tr>
 557 <tr class="markdownTableRowEven">
 558 <td class="markdownTableBodyNone">0x01   </td><td class="markdownTableBodyNone">Enable generation of error events    </td></tr>
 559 <tr class="markdownTableRowOdd">
 560 <td class="markdownTableBodyNone">0x05   </td><td class="markdownTableBodyNone">Enable generation of error and operational events    </td></tr>
 561 <tr class="markdownTableRowEven">
 562 <td class="markdownTableBodyNone">0x07   </td><td class="markdownTableBodyNone">Enable generation of error, API and operational events    </td></tr>
 563 <tr class="markdownTableRowOdd">
 564 <td class="markdownTableBodyNone">0x0F   </td><td class="markdownTableBodyNone">Enable generation of all events   </td></tr>
 565 </table>
 566 <p>Definitions <code>configEVR_LEVEL_x</code> set the recording level bitmask for events generated by each function group. They are taken into account only when recording level filter setup is enabled. Default value is <code>0x05</code>.</p>
 567 <h1><a class="anchor" id="autotoc_md4"></a>
 568 Debug a CMSIS-FreeRTOS Project</h1>
 569 <p><b>Note:</b> The following only applies when used with <a href="https://developer.arm.com/Tools%20and%20Software/Keil%20MDK">Arm Keil MDK</a>. If you are using a different toolchain, please consult its user's manual.</p>
 570 <p>Apart from the debug capabilities that <a class="el" href="#configure_evr">Event Recorder</a> offers, Keil MDK also supports thread-aware breakpoints, just like for the standard CMSIS-RTOS.</p>
 571 <h3>Code Example</h3>
 572 <div class="fragment"><div class="line">BS FuncN1, 1, &quot;break = (CURR_TID == tid_phaseA) ? 1 : 0&quot;</div>
 573 <div class="line">BS FuncN1, 1, &quot;break = (CURR_TID == tid_phaseA || CURR_TID == tid_phaseD) ? 1 : 0&quot;</div>
 574 <div class="line">BS \\Blinky\Blinky.c\FuncN1\179, 1, &quot;break = (CURR_TID == tid_phaseA || CURR_TID == tid_phaseD) ? 1 : 0&quot;</div>
 575 </div><!-- fragment --><blockquote class="doxtable">
 576 <p><b>Note:</b></p>
 577 <ul>
 578 <li>For more information on conditional breakpoints in Keil MDK, consult the <a href="https://developer.arm.com/documentation/101407/latest/Debugging/Debug-Windows-and-Dialogs/Breakpoints-Window">user's manual</a>.</li>
 579 <li>Enabling <a href="https://developer.arm.com/documentation/101407/latest/User-Interface/View-Menu">Periodic Window Update</a> is required to capture register values for active running threads while executing. When turned off, only the current FreeRTOS thread can be unwound after execution has been stopped. </li>
 580 </ul>
 581 </blockquote>
 582 <h3>Caveats</h3>
 583 <ul>
 584 <li>You cannot specify individual breakpoints on the same address. The following is not possible: <div class="fragment"><div class="line">BS ThCallee, 1, &quot;break = (CURR_TID==tid_phaseA) ? 1 : 0&quot;</div>
 585 <div class="line">BS ThCallee, 1, &quot;break = (CURR_TID==tid_phaseD) ? 1 : 0&quot;</div>
 586 </div><!-- fragment --> Instead, use this: <div class="fragment"><div class="line">BS ThCallee, 1, &quot;break= (CURR_TID==tid_phaseA || CURR_TID==tid_phaseD) ? 1 : 0&quot;</div>
 587 </div><!-- fragment --></li>
 588 <li>If you don't want to use <a href="https://developer.arm.com/documentation/101407/latest/User-Interface/View-Menu">Periodic Window Update</a>, obtain the thread and unwind information by adding a function that gets called from each thread of interest: <div class="fragment"><div class="line">_attribute_((noinline)) <span class="keywordtype">int</span> FuncN1 (<span class="keywordtype">int</span> n1) {</div>
 589 <div class="line">  ...</div>
 590 <div class="line">}</div>
 591 </div><!-- fragment --> Then, specify a thread-aware breakpoint using an "invalid" thread ID: <div class="fragment"><div class="line">BS FuncN1, 1, &quot;break = (CURR_TID == tid_phaseA + 1) ? 1 : 0&quot;</div>
 592 </div><!-- fragment --> &lsquo;'tid_phaseA&rsquo;<code>would be valid,</code>'tid_phaseA + 1'` is not but will still capture the most recent registers and store them to the actual thread context each time a thread-aware breakpoint is checked.</li>
 593 <li>Function inlining typically causes thread-aware breakpoints to fail. To avoid this, prepend the &lsquo;'noinline&rsquo;` attribute to the function that is used to stop when the current FreeRTOS thread id matches: <div class="fragment"><div class="line">_attribute_((noinline)) <span class="keywordtype">int</span> FuncN1 (<span class="keywordtype">int</span> n1) {</div>
 594 <div class="line">  ...</div>
 595 <div class="line">}</div>
 596 </div><!-- fragment --> This helps to make thread-aware breakpoints far less dependent on the compiler optimization level.</li>
 597 <li>Thread-aware breakpoints should be setup using a <a href="https://developer.arm.com/documentation/101407/latest/Debugging/Debug-Scripting">debug script</a>. Reason being that thread-aware breakpoints are of a 'hybrid' type, that is a combined address and condition expression that works best when run from a debug script. </li>
 598 </ul>
 599 </div></div><!-- contents -->
 600 </div><!-- PageDoc -->
 601 </div><!-- doc-content -->
 602 <!-- start footer part -->
 603 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 604   <ul>
 605     <li class="footer">
 606       <script type="text/javascript">
 607         <!--
 608         writeFooter.call(this);
 609         //-->
 610       </script>
 611     </li>
 612   </ul>
 613 </div>
 614 </body>
 615 </html>