diff options
Diffstat (limited to 'docs/RTOS2/html/genRTOS2IF.html')
| -rw-r--r-- | docs/RTOS2/html/genRTOS2IF.html | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/docs/RTOS2/html/genRTOS2IF.html b/docs/RTOS2/html/genRTOS2IF.html new file mode 100644 index 0000000..33583aa --- /dev/null +++ b/docs/RTOS2/html/genRTOS2IF.html @@ -0,0 +1,212 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<title>Generic RTOS Interface</title> +<title>CMSIS-RTOS2: Generic RTOS Interface</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<link href="cmsis.css" rel="stylesheet" type="text/css" /> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<script type="text/javascript" src="printComponentTabs.js"></script> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<script type="text/javascript"> + $(document).ready(initResizable); + $(window).load(resizeHeight); +</script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> + $(document).ready(function() { searchBox.OnSelectItem(0); }); +</script> +</head> +<body> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 46px;"> + <td id="projectlogo"><img alt="Logo" src="CMSIS_Logo_Final.png"/></td> + <td style="padding-left: 0.5em;"> + <div id="projectname">CMSIS-RTOS2 +  <span id="projectnumber">Version 2.1.3</span> + </div> + <div id="projectbrief">Real-Time Operating System: API and RTX Reference Implementation</div> + </td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<div id="CMSISnav" class="tabs1"> + <ul class="tablist"> + <script type="text/javascript"> + <!-- + writeComponentTabs.call(this); + //--> + </script> + </ul> +</div> +<!-- Generated by Doxygen 1.8.6 --> +<script type="text/javascript"> +var searchBox = new SearchBox("searchBox", "search",false,'Search'); +</script> + <div id="navrow1" class="tabs"> + <ul class="tablist"> + <li><a href="index.html"><span>Main Page</span></a></li> + <li class="current"><a href="pages.html"><span>Usage and Description</span></a></li> + <li><a href="modules.html"><span>Reference</span></a></li> + <li> + <div id="MSearchBox" class="MSearchBoxInactive"> + <span class="left"> + <img id="MSearchSelect" src="search/mag_sel.png" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + alt=""/> + <input type="text" id="MSearchField" value="Search" accesskey="S" + onfocus="searchBox.OnSearchFieldFocus(true)" + onblur="searchBox.OnSearchFieldFocus(false)" + onkeyup="searchBox.OnSearchFieldChange(event)"/> + </span><span class="right"> + <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a> + </span> + </div> + </li> + </ul> + </div> +</div><!-- top --> +<div id="side-nav" class="ui-resizable side-nav-resizable"> + <div id="nav-tree"> + <div id="nav-tree-contents"> + <div id="nav-sync" class="sync"></div> + </div> + </div> + <div id="splitbar" style="-moz-user-select:none;" + class="ui-resizable-handle"> + </div> +</div> +<script type="text/javascript"> +$(document).ready(function(){initNavTree('genRTOS2IF.html','');}); +</script> +<div id="doc-content"> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Pages</a></div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +<div class="header"> + <div class="headertitle"> +<div class="title">Generic RTOS Interface </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><p>CMSIS-RTOS2 is a generic API that is agnostic of the underlying RTOS kernel. Application programmers call CMSIS-RTOS2 API functions in the user code to ensure maximum portability from one RTOS to another. Middleware using CMSIS-RTOS2 API takes advantages of this approach by avoiding unnecessary porting efforts.</p> +<div class="image"> +<img src="API_Structure.png" alt="API_Structure.png"/> +<div class="caption"> +CMSIS-RTOS API Structure</div></div> +<p> A typical CMSIS-RTOS2 API implementation interfaces to an existing real-time kernel. The CMSIS-RTOS2 API provides the following attributes and functionalities:</p> +<ul> +<li>Function names, identifiers, and parameters are descriptive and easy to understand. The functions are powerful and flexible which reduces the number of functions exposed to the user.</li> +<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html">Thread Management</a> allows you to define, create, and control threads.</li> +<li>Interrupt Service Routines (ISR) can <a class="el" href="theory_of_operation.html#CMSIS_RTOS_ISR_Calls">call some CMSIS-RTOS functions</a>. When a CMSIS-RTOS function cannot be called from an ISR context, it rejects the invocation and returns an error code.</li> +<li>Three different event types support communication between multiple threads and/or ISR:<ul> +<li><a class="el" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html">Thread Flags</a>: may be used to indicate specific conditions to a thread.</li> +<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> +<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> +</ul> +</li> +<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> +<li>CPU time can be scheduled with the following functionalities:<ul> +<li>A <em>timeout</em> parameter is incorporated in many CMSIS-RTOS functions to avoid system lockup. When a timeout is specified, the system waits until a resource is available or an event occurs. While waiting, other threads are scheduled.</li> +<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> +<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> +</ul> +</li> +<li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html">Timer Management</a> functions are used to trigger the execution of functions.</li> +</ul> +<p>The CMSIS-RTOS2 API is designed to optionally incorporate multi-processor systems and/or access protection via the Cortex-M Memory Protection Unit (MPU).</p> +<p>In some RTOS implementations threads may execute on different processors, thus <b>message</b> queues may reside in shared memory resources.</p> +<p>The CMSIS-RTOS2 API encourages the software industry to evolve existing RTOS implementations. RTOS implementations can be different and optimized in various aspects towards the Cortex-M processors. Optional features may be for example</p> +<ul> +<li>Support of the Cortex-M Memory Protection Unit (MPU).</li> +<li>Support of multi-processor systems.</li> +<li>Support of a DMA controller.</li> +<li>Deterministic context switching.</li> +<li>Round-robin context switching.</li> +<li>Deadlock avoidance, for example with priority inversion.</li> +<li>Zero interrupt latency by using Armv7-M instructions LDREX and STREX.</li> +</ul> +<h1><a class="anchor" id="cmsis_os2_h"></a> +cmsis_os2.h header file</h1> +<p>The file <b>cmsis_os2.h</b> is a standard header file that interfaces to every CMSIS-RTOS2 compliant real-time operating systems (RTOS). Each implementation is provided the same <b><a class="el" href="cmsis__os2_8h.html">cmsis_os2.h</a></b> which defines the interface to the <a class="el" href="rtos_api2.html">CMSIS-RTOS C API v2</a>.</p> +<p>Using the <b><a class="el" href="cmsis__os2_8h.html">cmsis_os2.h</a></b> along with dynamic object allocation allows to create source code or libraries that require no modifications when using on a different CMSIS-RTOS2 implementation.</p> +<h1><a class="anchor" id="usingOS2"></a> +Using a CMSIS-RTOS2 Implementation</h1> +<p>A CMSIS-RTOS2 component may be provided as library or source code (the picture below shows a library). A CMSIS-based application is extended with RTOS functionality by adding a CMSIS-RTOS2 component (and typically some configuration files). The <a class="el" href="genRTOS2IF.html#cmsis_os2_h">cmsis_os2.h header file</a> gives access to RTOS API functions and is the only interface header required when dynamic object allocation is used. This enables portable application that works with every RTOS kernel event without re-compilation of the source code when the kernel is changed.</p> +<p>Static object allocation requires access to RTOS object control block definitions. An implementation specific header file (<em>rtos</em>.h in the picture below) provides access to such definitions. The section For RTX v5 these definitions are provided in the header file rtx_os.h that contains this definitions for RTX v5.</p> +<div class="image"> +<img src="CMSIS_RTOS_Files.png" alt="CMSIS_RTOS_Files.png"/> +<div class="caption"> +CMSIS-RTOS File Structure</div></div> +<p> Once the files are added to a project, the user can start working with the CMSIS-RTOS functions. A code example is provided below:</p> +<p><b>Code Example</b> </p> +<div class="fragment"><div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div> +<div class="line"><span class="comment"> * CMSIS-RTOS 'main' function template</span></div> +<div class="line"><span class="comment"> *---------------------------------------------------------------------------*/</span></div> +<div class="line"> </div> +<div class="line"><span class="preprocessor">#include "RTE_Components.h"</span></div> +<div class="line"><span class="preprocessor">#include CMSIS_device_header</span></div> +<div class="line"><span class="preprocessor"></span><span class="preprocessor">#include "<a class="code" href="cmsis__os2_8h.html">cmsis_os2.h</a>"</span></div> +<div class="line"> </div> +<div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div> +<div class="line"><span class="comment"> * Application main thread</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="comment">// ...</span></div> +<div class="line"> <span class="keywordflow">for</span> (;;) {}</div> +<div class="line">}</div> +<div class="line"> </div> +<div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div> +<div class="line"> </div> +<div class="line"> <span class="comment">// System Initialization</span></div> +<div class="line"> SystemCoreClockUpdate();</div> +<div class="line"><span class="preprocessor">#ifdef RTE_Compiler_EventRecorder</span></div> +<div class="line"><span class="preprocessor"></span> <span class="comment">// Initialize and start Event Recorder</span></div> +<div class="line"> EventRecorderInitialize(EventRecordError, 1U);</div> +<div class="line"><span class="preprocessor">#endif</span></div> +<div class="line"><span class="preprocessor"></span> <span class="comment">// ...</span></div> +<div class="line"> </div> +<div class="line"> <a class="code" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a>(); <span class="comment">// Initialize CMSIS-RTOS</span></div> +<div class="line"> <a class="code" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a>(app_main, NULL, NULL); <span class="comment">// Create application main thread</span></div> +<div class="line"> <a class="code" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>(); <span class="comment">// Start thread execution</span></div> +<div class="line"> <span class="keywordflow">for</span> (;;) {}</div> +<div class="line">}</div> +</div><!-- fragment --> </div></div><!-- contents --> +</div><!-- doc-content --> +<!-- start footer part --> +<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> + <ul> + <li class="navelem"><a class="el" href="index.html">index</a></li> + <li class="footer">Generated on Wed Aug 1 2018 17:12:45 for CMSIS-RTOS2 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 + --> + </li> + </ul> +</div> +</body> +</html> |