begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_MigrationGuide.txt

   1
   2
   3 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   4 /**
   5 \page os2MigrationGuide RTX Migration Guide
   6
   7 RTX5 supplies both API layers: CMSIS-RTOS v1 and CMSIS-RTOS v2. This allows a gradient transition from version 1 to 2. A
   8 modified v1 header and a special v1 compatibility module enable existing code to run on a v2 implementation with almost no
   9 modifications.
  10
  11 Only a few incompatibilities and limitations exist:
  12 - Kernel startup\n
  13   The function \c osKernelRunning has been deprecated. "main" was usually a running thread in v1 implementations, which is
  14   not the case in v2 anymore. It was also possible to not even initialize and start the Kernel, but just to assume that
  15   "main" was a running thread. Portable code would typically initialize the Kernel (\ref osKernelInitialize) and then start
  16   the Kernel (\ref osKernelStart) or skip that part if \c osKernelRunning indicated that it is already running.\n
  17   The example code below shows how to overcome this situation.
  18 - OS tick\n
  19   RTX5 uses the \ref CMSIS_RTOS_TickAPI to configure the tick interrupts. The interval calculation is typically based on
  20   \c SystemCoreClock variable. Thus one has to assure this variable is set correctly before calling \ref osKernelStart.
  21 - The function \c osWait is deprecated.
  22 - Error code incompatibility\n
  23   CMSIS-RTOS v1 used two different error codes for invalid parameters: \c osErrorParameter and \c osErrorValue. The new
  24   version only uses a common \ref osErrorParameter code. Therefore, code relying on osErrorValue is not compatible. The
  25   following functions are affected:
  26   - \ref osThreadSetPriority returns \ref osErrorParameter instead of osErrorValue when priority is out of range
  27   - \ref osMemoryPoolFree (previously \c osPoolFree) returns \ref osErrorParameter instead of osErrorValue when block to be
  28     returned is invalid
  29 - The \ref osDelay return code has changed from osErrorTimeout to \ref osOK.
  30
  31 The level of migration depends on the project's phase in its life cycle:
  32 - The \ref MigL1 "first level" of migration is to migrate to RTX5 without changing the API level.
  33 - The \ref MigL2 "second level" in the transition is to use v2 API functions and v1 API functions in mixed variation.
  34 - The \ref MigL3 "third level" is the full transition to the API v2. It is non-trivial and requires some additional
  35   development effort to migrate all API v1 calls to v2.
  36
  37
  38 \section MigL1 Level 1 Migration - Upgrade to RTX5 on API v1
  39
  40 Upgrade to RTX Version 5 from any 4.x version using the API v1 compatibility layer. Configure an existing project as follows:
  41
  42 - Open \b Manage \b Run-Time \b Environment window
  43 - Expand \b CMSIS software component.
  44 - Expand \b RTOS \b (API), uncheck \b Keil \b RTX, and select \b Keil \b RTX5.
  45 - Expand \b RTOS2 \b (API) and select \b Keil \b RTX5.
  46 - Resolve missing components.
  47
  48 \image html "RTX5_Migrate1.PNG" "Component Selection for RTX5"
  49
  50 - Click OK.
  51 - Expand \b CMSIS group in the \b Project window:
  52 - Open \b %RTX_Config.h and adapt the configuration to suit the application including (refer to \ref config_rtx5):
  53   - System Configuration->Global Dynamic Memory size
  54   - Kernel Tick Frequency
  55   - Thread Configuration->Default Thread Stack size
  56 - Rename function <tt>int main (void)</tt> to <tt>void app_main (void *arg)</tt>.
  57 - Create a new function <tt>int main (void)</tt> which implements at least:
  58   - System initialization and configuration
  59   - Update <a href="../../Core/html/group__system__init__gr.html">SystemCoreClock</a>
  60   - Initialize CMSIS-RTOS kernel
  61   - Creates new thread app_main
  62   - Start RTOS scheduler
  63
  64 <b>Example - Application Main Thread</b>
  65 \code
  66 #include "RTE_Components.h"
  67 #include CMSIS_device_header
  68
  69 /* Renamed main() function */
  70 void app_main (void const *argument) {
  71   // contents of old "main"
  72 }
  73
  74 osThreadDef(app_main, osPriorityNormal, 1, 0);
  75
  76 int main (void) {
  77   // System Initialization
  78   SystemCoreClockUpdate();
  79   // ...
  80   osKernelInitialize();
  81   osThreadCreate(osThread(app_main), NULL);
  82   osKernelStart();
  83   for (;;);
  84 }
  85 \endcode
  86
  87 \note In RTOS API v1 all timings were specified in milliseconds. RTX5 defines all times in kernel ticks.
  88 To match both it is recommended to set the Kernel Tick Frequency to 1000 Hz in the \ref systemConfig.
  89
  90 To validate the correct operation of your RTOS after migration you can temporarily integrate the \ref rtosValidation
  91 component into your project.
  92
  93
  94 \section MigL2 Level 2 Migration - Use API v2 and v1 alongside in RTX5
  95
  96 Implementing new features in your project is ideally done using the new API. Both API versions are offered in RTX5 and can
  97 exist along-side.
  98
  99 The component selection is identical to Migration Level 1.
 100
 101 Include "cmsis_os2.h" in all modules where access to API v2 functions is required.
 102
 103 \code
 104 #include "cmsis_os.h"                   // ARM::CMSIS:RTOS:Keil RTX5
 105 #include "cmsis_os2.h"                  // ARM::CMSIS:RTOS2:Keil RTX5
 106 \endcode
 107
 108 The following snippet shows how threads - created with both API versions - live along-side:
 109
 110 \code
 111 /*----------------------------------------------------------------------------
 112  *      Thread 4 'phaseD': Phase D output   - API v2 thread
 113  *---------------------------------------------------------------------------*/
 114 void phaseD (void *argument) {
 115   for (;;) {
 116     osThreadFlagsWait(0x0001, osFlagsWaitAny, osWaitForever);    /* wait for an event flag 0x0001 */
 117     Switch_On (LED_D);
 118     signal_func(tid_phaseA);                                     /* call common signal function   */
 119     Switch_Off(LED_D);
 120   }
 121 }
 122
 123 /*----------------------------------------------------------------------------
 124  *      Thread 5 'clock': Signal Clock  - API v1 thread
 125  *---------------------------------------------------------------------------*/
 126 void clock (void const *argument) {
 127   for (;;) {
 128     osSignalWait(0x0100, osWaitForever);    /*  Wait for event send by API v2 function osThreadFlagsSet() */
 129     Switch_On (LED_CLK);
 130     osDelay(80);                            /* delay ticks                    */
 131     Switch_Off(LED_CLK);
 132   }
 133 }
 134
 135 /* Define the API v1 thread */
 136 osThreadDef(clock,  osPriorityNormal, 1, 0);
 137
 138 /*----------------------------------------------------------------------------
 139  *      Main: Initialize and start RTX Kernel
 140  *---------------------------------------------------------------------------*/
 141 void app_main (void *argument) {
 142
 143   ; //...
 144   /* Create the API v2 thread */
 145   tid_phaseD = osThreadNew(phaseD, NULL, NULL);
 146   /* Create the API v1 thread */
 147   tid_clock  = osThreadCreate(osThread(clock),  NULL);
 148
 149   osThreadFlagsSet(tid_phaseA, 0x0001);          /* set signal to phaseA thread   */
 150
 151   osDelay(osWaitForever);
 152   while(1);
 153 }
 154 \endcode
 155
 156 The full example "RTX5 Migration" is part of the CMSIS5 pack and available from the pack installer.
 157
 158
 159 \section MigL3 Level 3 Migration - Full transition to API v2
 160 Migrating fully to APIv2 reduces the overhead of the translation layer and simplifies the project.
 161 There is some effort to replace and re-test all API Version 1 calls.
 162 The following steps are recommended as a rough guide-line:
 163 - Open Manage Run-Time Environment window:
 164 - Expand CMSIS Software Component:
 165 - Expand RTOS (API) Software Component and de-select Keil RTX5
 166 - Click OK
 167 - Exchange all occurrences of
 168   \code
 169   #include "cmsis_os.h"
 170   \endcode
 171   with
 172   \code
 173   #include "cmsis_os2.h"
 174   \endcode
 175 - Identify all references to the API v1 and replace with the appropriate calls in v2. You might want to use the Error List
 176   window in uVision to identify the related code passages quickly.
 177
 178 \note See \ref os2MigrationFunctions for details in differences.
 179
 180 Generally there are no longer os*Def macros to declare OS objects.
 181
 182 \note
 183 - Signal Events have been replaced. Use the functions listed under Thread Flags and Event Flags instead.
 184 - The Mail Queue RTOS v1 functions have been deprecated. Use the functionality of the Message Queue instead. Differences are
 185   listed under \ref mig_msgQueue.
 186 */
 187