Skip to content

Commit

Permalink
Updated documentation (CMSIS-FreeRTOS 10.4.3)
Browse files Browse the repository at this point in the history
  • Loading branch information
@VladimirUmek
VladimirUmek committed Sep 28, 2021
1 parent 36c231e commit 0a1cf28
Show file tree
Hide file tree
Showing 26 changed files with 319 additions and 152 deletions.
27 changes: 25 additions & 2 deletions docs/General/html/cm_revisionHistory.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">CMSIS-FreeRTOS
&#160;<span id="projectnumber">Version 10.3.1</span>
&#160;<span id="projectnumber">Version 10.4.3</span>
</div>
<div id="projectbrief">CMSIS-RTOS2 compliant FreeRTOS Implementation</div>
</td>
Expand Down Expand Up @@ -113,6 +113,29 @@
<div class="contents">
<div class="textblock"><table class="cmtable" summary="Revision History">
<tr>
<td>10.4.3 </td><td><p class="starttd"></p>
<p><b>FreeRTOS V10.4.3</b></p>
<p></p>
<p>Updates and bugfixes:</p>
<ul>
<li>
Corrected timeout handling in osThreadFlagsWait (#50) </li>
<li>
Enable full static memory allocation for timer object (#48) </li>
<li>
Fix vQueueAddToRegistry function call issue when arguments are NULL (#49) </li>
<li>
Added workaround for xEventGroupClearBitsFromISR no yield problem </li>
<li>
Added FreeRTOS kernel state check to osKernelInitialize and osKernelState </li>
<li>
Make source code more verbose with documented limitations (#41) </li>
<li>
Fix osMemoryPoolNew expression use (#42) </li>
</ul>
<p class="endtd"></p>
</td></tr>
<tr>
<td>10.3.1 </td><td><p class="starttd"></p>
<p><b>FreeRTOS V10.3.1</b></p>
<p></p>
Expand Down Expand Up @@ -211,7 +234,7 @@
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Thu Apr 30 2020 11:16:53 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<li class="footer">Generated on Tue Sep 28 2021 12:31:55 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<!--
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
Expand Down
134 changes: 131 additions & 3 deletions docs/General/html/cre_freertos_proj.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">CMSIS-FreeRTOS
&#160;<span id="projectnumber">Version 10.3.1</span>
&#160;<span id="projectnumber">Version 10.4.3</span>
</div>
<div id="projectbrief">CMSIS-RTOS2 compliant FreeRTOS Implementation</div>
</td>
Expand Down Expand Up @@ -141,6 +141,32 @@ <h2><a class="anchor" id="native_freertos_config"></a>
<div class="image">
<img src="freertos_config_h_native.png" alt="freertos_config_h_native.png"/>
</div>
<h2><a class="anchor" id="native_freertos_config_prio"></a>
Interrupt priority configuration</h2>
<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" target="_blank">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>
<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>
<table class="doxtable">
<tr>
<th align="center"><code>configMAX_SYSCALL_INTERRUPT_PRIORITY</code> </th><th align="center">Upper three bits </th><th align="center">Priority </th></tr>
<tr>
<td align="center">32 </td><td align="center">001 </td><td align="center">1 (Highest) </td></tr>
<tr>
<td align="center">64 </td><td align="center">010 </td><td align="center">2 </td></tr>
<tr>
<td align="center">96 </td><td align="center">011 </td><td align="center">3 </td></tr>
<tr>
<td align="center">128 </td><td align="center">100 </td><td align="center">4 </td></tr>
<tr>
<td align="center">160 </td><td align="center">101 </td><td align="center">5 </td></tr>
<tr>
<td align="center">196 </td><td align="center">110 </td><td align="center">6 </td></tr>
<tr>
<td align="center">224 </td><td align="center">111 </td><td align="center">7 (Lowest) </td></tr>
</table>
<p><b>Example</b> </p>
<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 critical a section.</p>
<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>
<dl class="section note"><dt>Note</dt><dd>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" target="_blank">Running the RTOS on a ARM Cortex-M Core</a>.</dd></dl>
<h2><a class="anchor" id="native_freertos_er"></a>
Add Event Recorder Visibility</h2>
<ul>
Expand Down Expand Up @@ -223,6 +249,7 @@ <h2><a class="anchor" id="cmsis_freertos_config"></a>
<tr>
<td>Queue registry size </td><td>configQUEUE_REGISTRY_SIZE </td><td>Define maximum number of queue objects registered for debug purposes. </td></tr>
</table>
<dl class="section note"><dt>Note</dt><dd>Refer to <a class="el" href="cre_freertos_proj.html#native_freertos_config_prio">Interrupt priority configuration</a> for more information on the usage of <code>configMAX_SYSCALL_INTERRUPT_PRIORITY</code>.</dd></dl>
<p><b> Event Recorder Configuration </b></p>
<p>The following settings are available (see <a class="el" href="cre_freertos_proj.html#cmsis_freertos_evr_config">Configure Event Recorder</a> for details):</p>
<table class="doxtable">
Expand Down Expand Up @@ -267,6 +294,77 @@ <h2><a class="anchor" id="cmsis_freertos_er"></a>
<li>Build the application code and download it to the debug hardware or run it in simulation.</li>
</ul>
<p>Once the target application generates event information, it can be viewed in the µVision debugger using the <b>Event Recorder.</b></p>
<h1><a class="anchor" id="freertos_interfaces"></a>
Create a mixed-interface project</h1>
<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="cre_freertos_proj.html#cmsis_freertos">created as CMSIS-FreeRTOS project</a>.</p>
<p>Depending on the application requirements, FreeRTOS kernel can be started either by using FreeRTOS native API or by using CMSIS-RTOS2 API.</p>
<h2><a class="anchor" id="freertos_interface_rtos2"></a>
Start the kernel using CMSIS-RTOS2 API</h2>
<div class="fragment"><div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> Application thread: Initialize and start the Application</span></div>
<div class="line"><span class="comment">*/</span></div>
<div class="line"><span class="keywordtype">void</span> app_main (<span class="keywordtype">void</span> *argument) {</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">while</span>(1) {</div>
<div class="line"> <span class="comment">// Application code</span></div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> Main function: Initialize and start the kernel</span></div>
<div class="line"><span class="comment">*/</span></div>
<div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
<div class="line"> SystemCoreClockUpdate();</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Initialize CMSIS-RTOS2</span></div>
<div class="line"> osKernelInitialize();</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Create application main thread</span></div>
<div class="line"> osThreadNew(app_main, NULL, NULL);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Start the kernel and execute the first thread</span></div>
<div class="line"> osKernelStart();</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">while</span>(1);</div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Restrictions</b> </p>
<p>After the kernel is started using CMSIS-RTOS2 API, FreeRTOS native API can be used with the following restrictions:</p>
<ul>
<li>vTaskStartScheduler must not be called</li>
</ul>
<h2><a class="anchor" id="freertos_interface_native"></a>
Start the kernel using native API</h2>
<div class="fragment"><div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> Application main thread: Initialize and start the application</span></div>
<div class="line"><span class="comment">*/</span></div>
<div class="line"><span class="keywordtype">void</span> app_main (<span class="keywordtype">void</span> *argument) {</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">while</span>(1) {</div>
<div class="line"> <span class="comment">// Application code</span></div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> Main function: Initialize and start the kernel</span></div>
<div class="line"><span class="comment">*/</span></div>
<div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
<div class="line"> SystemCoreClockUpdate();</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Setup the Event Recorder (optionally)</span></div>
<div class="line"> <a class="code" href="group__freertos__setup.html#ga943f40b05c79f40c73d67b1adcbe3dbe">EvrFreeRTOSSetup</a>(0);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Create application main thread</span></div>
<div class="line"> xTaskCreate (app_main, <span class="stringliteral">&quot;app_main&quot;</span>, 64, NULL, tskIDLE_PRIORITY+1, NULL);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Start the kernel and execute the first thread</span></div>
<div class="line"> vTaskStartScheduler();</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">while</span>(1);</div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Restrictions</b> </p>
<p>After the kernel is started using FreeRTOS native API, CMSIS-RTOS2 API can be used without restrictions.</p>
<h1><a class="anchor" id="cmsis_freertos_evr_config"></a>
Configure Event Recorder</h1>
<p>This section describes the configuration settings for the <a href="http://www.keil.com/pack/doc/compiler/EventRecorder/html/index.html" target="_blank">Event Recorder</a> annotations. For more information refer to section <a class="el" href="cre_freertos_proj.html#native_freertos_er">Add Event Recorder Visibility to native FreeRTOS project</a> or <a class="el" href="cre_freertos_proj.html#cmsis_freertos_er">Add Event Recorder Visibility to CMSIS-FreeRTOS project</a>.</p>
Expand Down Expand Up @@ -309,13 +407,43 @@ <h1><a class="anchor" id="cmsis_freertos_evr_config"></a>
<tr>
<td>0x0F </td><td>Enable generation of all events </td></tr>
</table>
<p>Definitions configEVR_LEVEL_x 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 <span class="XML-Token">0x05</span>. </p>
<p>Definitions configEVR_LEVEL_x 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 <span class="XML-Token">0x05</span>.</p>
<h1><a class="anchor" id="dbg_cmsisfreertos"></a>
Debug a CMSIS-FreeRTOS project</h1>
<dl class="section note"><dt>Note</dt><dd>The following only applies when used with <a href="https://www2.keil.com/mdk5" target="_blank">Arm Keil MDK</a>. If you are using a different toolchain, please consult its user's manual.</dd></dl>
<p>Apart from the debug capabilities that <a class="el" href="cre_freertos_proj.html#cmsis_freertos_evr_config">Event Recorder</a> offers, Keil MDK also supports thread aware breakpoints, just like for the standard CMSIS-RTOS.</p>
<p><b>Code</b> <b>Example</b> </p>
<div class="fragment"><div class="line">BS FuncN1, 1, <span class="stringliteral">&quot;break = (CURR_TID == tid_phaseA) ? 1 : 0&quot;</span></div>
<div class="line">BS FuncN1, 1, <span class="stringliteral">&quot;break = (CURR_TID == tid_phaseA || CURR_TID == tid_phaseD) ? 1 : 0&quot;</span></div>
<div class="line">BS \\Blinky\Blinky.c\FuncN1\179, 1, <span class="stringliteral">&quot;break = (CURR_TID == tid_phaseA || CURR_TID == tid_phaseD) ? 1 : 0&quot;</span></div>
</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd><ul>
<li>For more information on conditional breakpoints in Keil MDK, consult the <a href="https://www.keil.com/support/man/docs/uv4/uv4_db_dbg_breakpnts.htm" target="_blank">user's manual</a>.</li>
<li>Enabling <a href="https://www.keil.com/support/man/docs/uv4/uv4_ui_view.htm" target="_blank">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>
</ul>
</dd></dl>
<p><b>Caveats</b> </p>
<ul>
<li>You cannot specify individual breakpoints on the same address. The following is not possible: <div class="fragment"><div class="line">BS ThCallee, 1, <span class="stringliteral">&quot;break = (CURR_TID==tid_phaseA) ? 1 : 0&quot;</span></div>
<div class="line">BS ThCallee, 1, <span class="stringliteral">&quot;break = (CURR_TID==tid_phaseD) ? 1 : 0&quot;</span></div>
</div><!-- fragment --> Instead, use this: <div class="fragment"><div class="line">BS ThCallee, 1, <span class="stringliteral">&quot;break= (CURR_TID==tid_phaseA || CURR_TID==tid_phaseD) ? 1 : 0&quot;</span></div>
</div><!-- fragment --></li>
<li>If you don't want to use <a href="https://www.keil.com/support/man/docs/uv4/uv4_ui_view.htm" target="_blank">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)) int FuncN1 (<span class="keywordtype">int</span> n1) {</div>
<div class="line"> ...</div>
<div class="line">} </div>
</div><!-- fragment --> Then, specify a thread aware breakpoint using an "invalid" thread ID: <div class="fragment"><div class="line">BS FuncN1, 1, <span class="stringliteral">&quot;break = (CURR_TID == tid_phaseA + 1) ? 1 : 0&quot;</span></div>
</div><!-- fragment --> <code>'tid_phaseA'</code> would be valid, <code>'tid_phaseA + 1'</code> 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>
<li>Function inlining typically causes thread aware breakpoints to fail. To avoid this, prepend the <code>'noinline'</code> attribute to the function that is used to stop when the current FreeRTOS thread id matches: <div class="fragment"><div class="line">_attribute_((noinline)) int FuncN1 (<span class="keywordtype">int</span> n1) {</div>
<div class="line"> ...</div>
<div class="line">}</div>
</div><!-- fragment --> This helps to make thread aware breakpoints far less dependent on the compiler optimization level.</li>
<li>Thread aware breakpoints should be setup using a <a href="https://www.keil.com/support/man/docs/uv4/uv4_db_scripting.htm" target="_blank">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>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Thu Apr 30 2020 11:16:53 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<li class="footer">Generated on Tue Sep 28 2021 12:31:55 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<!--
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
Expand Down
4 changes: 2 additions & 2 deletions docs/General/html/dir_46cf4373772806b8331687559c626178.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">CMSIS-FreeRTOS
&#160;<span id="projectnumber">Version 10.3.1</span>
&#160;<span id="projectnumber">Version 10.4.3</span>
</div>
<div id="projectbrief">CMSIS-RTOS2 compliant FreeRTOS Implementation</div>
</td>
Expand Down Expand Up @@ -123,7 +123,7 @@
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="dir_e7fa9f9ff84ec6f18f923fb2418bfd4b.html">CMSIS</a></li><li class="navelem"><a class="el" href="dir_6fbc6882f8daffdaafc25c2f1839223d.html">RTOS2</a></li><li class="navelem"><a class="el" href="dir_4c727e77617e41be30cca75e10c711ee.html">FreeRTOS</a></li><li class="navelem"><a class="el" href="dir_46cf4373772806b8331687559c626178.html">Include</a></li>
<li class="footer">Generated on Thu Apr 30 2020 11:16:53 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<li class="footer">Generated on Tue Sep 28 2021 12:31:56 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<!--
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
Expand Down
4 changes: 2 additions & 2 deletions docs/General/html/dir_4c727e77617e41be30cca75e10c711ee.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
<td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">CMSIS-FreeRTOS
&#160;<span id="projectnumber">Version 10.3.1</span>
&#160;<span id="projectnumber">Version 10.4.3</span>
</div>
<div id="projectbrief">CMSIS-RTOS2 compliant FreeRTOS Implementation</div>
</td>
Expand Down Expand Up @@ -123,7 +123,7 @@
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="dir_e7fa9f9ff84ec6f18f923fb2418bfd4b.html">CMSIS</a></li><li class="navelem"><a class="el" href="dir_6fbc6882f8daffdaafc25c2f1839223d.html">RTOS2</a></li><li class="navelem"><a class="el" href="dir_4c727e77617e41be30cca75e10c711ee.html">FreeRTOS</a></li>
<li class="footer">Generated on Thu Apr 30 2020 11:16:53 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<li class="footer">Generated on Tue Sep 28 2021 12:31:56 for CMSIS-FreeRTOS by ARM Ltd. All rights reserved.
<!--
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6
Expand Down
Loading

0 comments on commit 0a1cf28

Please sign in to comment.