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.
   8 Depending on the phase a project is in its life cycly a level of migration is chosen.
   9
  10 - The first level of migration is to migrate to RTX5 without changing the API level.
  11 - The second level in the transition is to use Version 2 API functions and Version 1 API functions in mixed variation.
  12 - The third level is non-trivial and requires some additional development effort to migrate all API Version 1 calls to Version 2.
  13
  14 \section MigL1 Level 1 Migration - Upgrade to RTX5 on API v1
  15
  16 The Upgrade to RTX Version 5 from any version 4.x is simple using the API v1 compatibility layer. To configure this in an existing project the following steps are required:
  17
  18 \image html "RTX5_Migrate1.PNG" "Component Selection for RTX5"
  19
  20 -# Open Manage Run-Time Environment window:
  21 -# Expand CMSIS Software Component.
  22 -# Expand RTOS (API) and deselect Keil RTX.
  23 -# Select Keil RTX5 from the RTOS (API) group.
  24 -# Resolve the missing components.
  25 -# Click OK.
  26 -# Expand CMSIS group in the Project window:
  27 -# Open RTX_Config.c and adapt configuration to suit the application including:
  28         - System Configuration->Global Dynamic Memory size
  29         - Kernel Tick Frequency
  30         - Thread Configuration->Default Thread Stack size
  31         - Details are found in \ref config_rtx
  32 -# Rename function int \b main (void) to void \b app_main (void *arg).
  33 Create new function int main (void) which implements at least:
  34         - System initialization and configuration
  35         - Update SystemCoreClock
  36         - Initialize CMSIS-RTOS kernel
  37         - Creates new thread app_main
  38         - Start RTOS scheduler
  39
  40 <b>Example - Application Main Thread</b>
  41 \code{.c}
  42 /* Renamed main() function */
  43 void app_main (void *arg) {
  44
  45   while (1) {
  46     /* .. */
  47     ;
  48   }
  49 }
  50
  51 /* New main function to start app_main */
  52 int main (void) {
  53   Init_Hardware();
  54
  55   // System Initialization
  56   SystemCoreClockUpdate();
  57   // ...
  58   osKernelInitialize();                 // Initialize CMSIS-RTOS
  59   osThreadNew(app_main, NULL, NULL);    // Create application main thread
  60   if (osKernelGetState() == osKernelReady) {
  61     osKernelStart();                    // Start thread execution
  62   }
  63   while(1);
  64 }
  65 \endcode
  66
  67 \note In RTOS API v1 all timings were specified in milliseconds. RTX5 defines all times in kernel ticks.
  68 To match both it is recommended to set the Kernel Tick Frequency to 1000Hz in the \ref SystemConfig.
  69
  70 To validate the correct operation of your RTOS after migration you can temporarily integrate the \ref rtosValidation component into your project.
  71
  72 \section MigL2 Level 2 Migration - Use API v2 and v1 alongside in RTX5
  73
  74 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.
  75
  76 The component selection is identical to Migration Level 1.
  77
  78 Include "cmsis_os2.h" in all modules where access to API v2 functions is required.
  79
  80 \code{.c}
  81 #include "cmsis_os.h"                   // ARM::CMSIS:RTOS:Keil RTX5
  82 #include "cmsis_os2.h"                  // ARM::CMSIS:RTOS2:Keil RTX5
  83 \endcode
  84
  85 The following snippet shows how threads - created with both API versions - live along-side:
  86
  87 \code{.c}
  88 /*----------------------------------------------------------------------------
  89  *      Thread 4 'phaseD': Phase D output   - API v2 thread
  90  *---------------------------------------------------------------------------*/
  91 void phaseD (void *argument) {
  92   for (;;) {
  93     osThreadFlagsWait(0x0001, osFlagsWaitAny, osWaitForever);    /* wait for an event flag 0x0001 */
  94     Switch_On (LED_D);
  95     signal_func(tid_phaseA);                                     /* call common signal function   */
  96     Switch_Off(LED_D);
  97   }
  98 }
  99
 100 /*----------------------------------------------------------------------------
 101  *      Thread 5 'clock': Signal Clock  - API v1 thread
 102  *---------------------------------------------------------------------------*/
 103 void clock (void const *argument) {
 104   for (;;) {
 105     osSignalWait(0x0100, osWaitForever);    /*  Wait for event send by API v2 function osThreadFlagsSet() */
 106     Switch_On (LED_CLK);
 107     osDelay(80);                            /* delay ticks                    */
 108     Switch_Off(LED_CLK);
 109   }
 110 }
 111
 112 /* Define the API v1 thread */
 113 osThreadDef(clock,  osPriorityNormal, 1, 0);
 114
 115 /*----------------------------------------------------------------------------
 116  *      Main: Initialize and start RTX Kernel
 117  *---------------------------------------------------------------------------*/
 118 void app_main (void *argument) {
 119
 120   ; //...
 121   /* Create the API v2 thread */
 122   tid_phaseD = osThreadNew(phaseD, NULL, NULL);
 123   /* Create the API v1 thread */
 124   tid_clock  = osThreadCreate(osThread(clock),  NULL);
 125
 126   osThreadFlagsSet(tid_phaseA, 0x0001);          /* set signal to phaseA thread   */
 127
 128   osDelay(osWaitForever);
 129   while(1);
 130 }
 131 \endcode
 132
 133 The full example "RTX5 Migration" is part of the CMSIS5 pack and available from the pack installer.
 134
 135 \section MigL3 Level 3 Migration - Full transition to API v2
 136 Migrating fully to APIv2 reduces the overhead of the translation layer and simplifies the project.
 137 There is some effort to replace and re-test all API Version 1 calls.
 138 The following steps are recommended as a rough guide-line:
 139 -# Open Manage Run-Time Environment window:
 140 -# Expand CMSIS Software Component:
 141 -# Expand RTOS (API) Software Component and de-select Keil RTX5
 142 -# Click OK
 143 -# Remove all occurances of
 144         \code{.c}
 145         #include "cmsis_os.h"
 146         \endcode
 147 -# 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.
 148
 149 \note See \ref os2MigrationFunctions for details in differences.
 150
 151 Generally there are now longer os*Def macros to declare OS objects.
 152
 153 \note Signal Events have been replaced. Use the functions listed under Thread Flags and Event Flags instead.
 154 \note The Mail Queue RTOS v1 functions have been deprecated. Use the functionality of the Message Queue instead. Differences are listed under \ref mig_msgQueue.
 155
 156
 157 \todo Kernel Ticks needs to be added to SystemConfig documentation
 158
 159 */
 160
 161