1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
|
<!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>RTX Migration Guide</title>
<title>CMSIS-RTOS2: RTX Migration Guide</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('os2MigrationGuide.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">RTX Migration Guide </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>RTX5 supplies both API layers: CMSIS-RTOS v1 and CMSIS-RTOS v2. This allows a gradient transition from version 1 to 2. A modified v1 header and a special v1 compatibility module enable existing code to run on a v2 implementation with almost no modifications.</p>
<p>Only a few incompatibilities and limitations exist:</p>
<ul>
<li>Kernel startup<br/>
<ul>
<li>The function <code>osKernelRunning</code> has been removed in CMSIS-RTOS v2, use <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga48b69b81012fce051f639be288b243ba" title="Get the current RTOS Kernel state. ">osKernelGetState()</a> instead.</li>
<li>Function <code>main</code> was usually a running thread in CMSIS-RTOS v1 implementations, which is not the case in CMSIS-RTOS v2 anymore. The Kernel was running even without calling corresponding APIs to initialize and start the Kernel explicitly. In CMSIS-RTOS v2 the Kernel needs be initialized by calling <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659" title="Initialize the RTOS Kernel. ">osKernelInitialize()</a> and must be started by calling <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221" title="Start the RTOS Kernel scheduler. ">osKernelStart()</a>.</li>
</ul>
</li>
<li>OS tick<br/>
RTX5 uses the <a class="el" href="group__CMSIS__RTOS__TickAPI.html">OS Tick API</a> to configure the tick interrupts. The interval calculation is typically based on <code>SystemCoreClock</code> variable. Thus one has to assure this variable is set correctly before calling <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>.</li>
<li>The function <code>osWait</code> is deprecated.</li>
<li>Error code incompatibility<br/>
CMSIS-RTOS v1 used two different error codes for invalid parameters: <code>osErrorParameter</code> and <code>osErrorValue</code>. The new version only uses a common <a class="el" href="cmsis__os2_8h.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813eac24adca6a5d072c9f01c32178ba0d109">osErrorParameter</a> code. Therefore, code relying on osErrorValue is not compatible. The following functions are affected:<ul>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga861a420fb2d643115b06622903fb3bfb">osThreadSetPriority</a> returns <a class="el" href="cmsis__os2_8h.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813eac24adca6a5d072c9f01c32178ba0d109">osErrorParameter</a> instead of osErrorValue when priority is out of range</li>
<li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gabb4f4560daa6d1f8c8789082ee186d16">osMemoryPoolFree</a> (previously <code>osPoolFree</code>) returns <a class="el" href="cmsis__os2_8h.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813eac24adca6a5d072c9f01c32178ba0d109">osErrorParameter</a> instead of osErrorValue when block to be returned is invalid</li>
</ul>
</li>
<li>The <a class="el" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e">osDelay</a> return code has changed from osErrorTimeout to <a class="el" href="cmsis__os2_8h.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813ea9e1c9e2550bb4de8969a935acffc968f">osOK</a>.</li>
</ul>
<p>The level of migration depends on the project's phase in its life cycle:</p>
<ul>
<li>The <a class="el" href="os2MigrationGuide.html#MigL1">first level</a> of migration is to migrate to RTX5 without changing the API level.</li>
<li>The <a class="el" href="os2MigrationGuide.html#MigL2">second level</a> in the transition is to use v2 API functions and v1 API functions in mixed variation.</li>
<li>The <a class="el" href="os2MigrationGuide.html#MigL3">third level</a> is the full transition to the API v2. It is non-trivial and requires some additional development effort to migrate all API v1 calls to v2.</li>
</ul>
<h1><a class="anchor" id="MigL1"></a>
Level 1 Migration - Upgrade to RTX5 on API v1</h1>
<p>Upgrade to RTX Version 5 from any 4.x version using the API v1 compatibility layer. Configure an existing project as follows:</p>
<ul>
<li>Open <b>Manage</b> <b>Run-Time</b> <b>Environment</b> window</li>
<li>Expand <b>CMSIS</b> software component.</li>
<li>Expand <b>RTOS</b> <b></b>(API), uncheck <b>Keil</b> <b>RTX</b>, and select <b>Keil</b> <b>RTX5</b>.</li>
<li>Expand <b>RTOS2</b> <b></b>(API) and select <b>Keil</b> <b>RTX5</b>.</li>
<li>Resolve missing components.</li>
</ul>
<div class="image">
<img src="RTX5_Migrate1.PNG" alt="RTX5_Migrate1.PNG"/>
<div class="caption">
Component Selection for RTX5</div></div>
<ul>
<li>Click OK.</li>
<li>Expand <b>CMSIS</b> group in the <b>Project</b> window:</li>
<li>Open <b>RTX_Config.h</b> and adapt the configuration to suit the application including (refer to <a class="el" href="config_rtx5.html">Configure RTX v5</a>):<ul>
<li>System Configuration->Global Dynamic Memory size</li>
<li>Kernel Tick Frequency</li>
<li>Thread Configuration->Default Thread Stack size</li>
</ul>
</li>
<li>Rename function <code>int main (void)</code> to <code>void app_main (void *arg)</code>.</li>
<li>Create a new function <code>int main (void)</code> which implements at least:<ul>
<li>System initialization and configuration</li>
<li>Update <a href="../../Core/html/group__system__init__gr.html">SystemCoreClock</a></li>
<li>Initialize CMSIS-RTOS kernel</li>
<li>Creates new thread app_main</li>
<li>Start RTOS scheduler</li>
</ul>
</li>
</ul>
<p><b>Example - Application Main Thread</b> </p>
<div class="fragment"><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> </div>
<div class="line"><span class="comment">/* Renamed main() function */</span></div>
<div class="line"><span class="keywordtype">void</span> app_main (<span class="keywordtype">void</span> <span class="keyword">const</span> *argument) {</div>
<div class="line"> <span class="comment">// contents of old "main"</span></div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">osThreadDef(app_main, <a class="code" href="cmsis__os2_8h.html#gad4e3e0971b41f2d17584a8c6837342eca45a2895ad30c79fb97de18cac7cc19f1">osPriorityNormal</a>, 1, 0);</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
<div class="line"> <span class="comment">// System Initialization</span></div>
<div class="line"> SystemCoreClockUpdate();</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a>();</div>
<div class="line"> osThreadCreate(osThread(app_main), NULL);</div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>();</div>
<div class="line"> <span class="keywordflow">for</span> (;;);</div>
<div class="line">}</div>
</div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>In RTOS API v1 all timings were specified in milliseconds. RTX5 defines all times in kernel ticks. To match both it is recommended to set the Kernel Tick Frequency to 1000 Hz in the <a class="el" href="config_rtx5.html#systemConfig">System Configuration</a>.</dd></dl>
<p>To validate the correct operation of your RTOS after migration you can temporarily integrate the <a class="el" href="rtosValidation.html">RTOS Validation</a> component into your project.</p>
<h1><a class="anchor" id="MigL2"></a>
Level 2 Migration - Use API v2 and v1 alongside in RTX5</h1>
<p>Implementing new features in your project is ideally done using the new API. Both API versions are offered in RTX5 and can exist along-side.</p>
<p>The component selection is identical to Migration Level 1.</p>
<p>Include "cmsis_os2.h" in all modules where access to API v2 functions is required.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "cmsis_os.h"</span> <span class="comment">// ARM::CMSIS:RTOS:Keil RTX5</span></div>
<div class="line"><span class="preprocessor">#include "<a class="code" href="cmsis__os2_8h.html">cmsis_os2.h</a>"</span> <span class="comment">// ARM::CMSIS:RTOS2:Keil RTX5</span></div>
</div><!-- fragment --><p>The following snippet shows how threads - created with both API versions - live along-side:</p>
<div class="fragment"><div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div>
<div class="line"><span class="comment"> * Thread 4 'phaseD': Phase D output - API v2 thread</span></div>
<div class="line"><span class="comment"> *---------------------------------------------------------------------------*/</span></div>
<div class="line"><span class="keywordtype">void</span> phaseD (<span class="keywordtype">void</span> *argument) {</div>
<div class="line"> <span class="keywordflow">for</span> (;;) {</div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html#gac11542ad6300b600f872fc96e340ec2b">osThreadFlagsWait</a>(0x0001, <a class="code" href="group__CMSIS__RTOS__Definitions.html#ga18e63587b8450d5b8798b6f6ec04e012">osFlagsWaitAny</a>, <a class="code" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb">osWaitForever</a>); <span class="comment">/* wait for an event flag 0x0001 */</span></div>
<div class="line"> Switch_On (LED_D);</div>
<div class="line"> signal_func(tid_phaseA); <span class="comment">/* call common signal function */</span></div>
<div class="line"> Switch_Off(LED_D);</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"> * Thread 5 'clock': Signal Clock - API v1 thread</span></div>
<div class="line"><span class="comment"> *---------------------------------------------------------------------------*/</span></div>
<div class="line"><span class="keywordtype">void</span> clock (<span class="keywordtype">void</span> <span class="keyword">const</span> *argument) {</div>
<div class="line"> <span class="keywordflow">for</span> (;;) {</div>
<div class="line"> osSignalWait(0x0100, <a class="code" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb">osWaitForever</a>); <span class="comment">/* Wait for event send by API v2 function osThreadFlagsSet() */</span></div>
<div class="line"> Switch_On (LED_CLK);</div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e">osDelay</a>(80); <span class="comment">/* delay ticks */</span></div>
<div class="line"> Switch_Off(LED_CLK);</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><span class="comment">/* Define the API v1 thread */</span></div>
<div class="line">osThreadDef(clock, <a class="code" href="cmsis__os2_8h.html#gad4e3e0971b41f2d17584a8c6837342eca45a2895ad30c79fb97de18cac7cc19f1">osPriorityNormal</a>, 1, 0);</div>
<div class="line"> </div>
<div class="line"><span class="comment">/*----------------------------------------------------------------------------</span></div>
<div class="line"><span class="comment"> * Main: Initialize and start RTX Kernel</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="comment">/* Create the API v2 thread */</span></div>
<div class="line"> tid_phaseD = <a class="code" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a>(phaseD, NULL, NULL);</div>
<div class="line"> <span class="comment">/* Create the API v1 thread */</span></div>
<div class="line"> tid_clock = osThreadCreate(osThread(clock), NULL);</div>
<div class="line"> </div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html#ga6f89ef9caded1d9963c7b12b0f6412c9">osThreadFlagsSet</a>(tid_phaseA, 0x0001); <span class="comment">/* set signal to phaseA thread */</span></div>
<div class="line"> </div>
<div class="line"> <a class="code" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e">osDelay</a>(<a class="code" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb">osWaitForever</a>);</div>
<div class="line"> <span class="keywordflow">while</span>(1);</div>
<div class="line">}</div>
</div><!-- fragment --><p>The full example "RTX5 Migration" is part of the CMSIS5 pack and available from the pack installer.</p>
<h1><a class="anchor" id="MigL3"></a>
Level 3 Migration - Full transition to API v2</h1>
<p>Migrating fully to APIv2 reduces the overhead of the translation layer and simplifies the project. There is some effort to replace and re-test all API Version 1 calls. The following steps are recommended as a rough guide-line:</p>
<ul>
<li>Open Manage Run-Time Environment window:</li>
<li>Expand CMSIS Software Component:</li>
<li>Expand RTOS (API) Software Component and de-select Keil RTX5</li>
<li>Click OK</li>
<li>Exchange all occurrences of <div class="fragment"><div class="line"><span class="preprocessor">#include "cmsis_os.h"</span> </div>
</div><!-- fragment --> with <div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="cmsis__os2_8h.html">cmsis_os2.h</a>"</span> </div>
</div><!-- fragment --></li>
<li>Identify all references to the API v1 and replace with the appropriate calls in v2. You might want to use the Error List window in uVision to identify the related code passages quickly.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>See <a class="el" href="os2MigrationFunctions.html">Detailed API Function Differences</a> for details in differences.</dd></dl>
<p>Generally there are no longer os*Def macros to declare OS objects.</p>
<dl class="section note"><dt>Note</dt><dd><ul>
<li>Signal Events have been replaced. Use the functions listed under Thread Flags and Event Flags instead.</li>
<li>The Mail Queue RTOS v1 functions have been deprecated. Use the functionality of the Message Queue instead. Differences are listed under <a class="el" href="os2MigrationFunctions.html#mig_msgQueue">Message Queue</a>. </li>
</ul>
</dd></dl>
</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="navelem"><a class="el" href="os2Migration.html">Migration from API v1 to API v2</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>
|
