CMSIS-RTOS2  Version 2.0.0
Real-Time Operating System: API and RTX Reference Implementation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
RTX Migration Guide

RTX5 supplies both API layers: CMSIS-RTOS v1 and CMSIS-RTOS v2. This allows a gradient transition from version 1 to 2. Depending on the phase a project is in its life cycly a level of migration is chosen.

  • The first level of migration is to migrate to RTX5 without changing the API level.
  • The second level in the transition is to use Version 2 API functions and Version 1 API functions in mixed variation.
  • The third level is non-trivial and requires some additional development effort to migrate all API Version 1 calls to Version 2.

Level 1 Migration - Upgrade to RTX5 on API v1

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:

RTX5_Migrate1.PNG
Component Selection for RTX5
  1. Open Manage Run-Time Environment window:
  2. Expand CMSIS Software Component.
  3. Expand RTOS (API) and deselect Keil RTX.
  4. Select Keil RTX5 from the RTOS (API) group.
  5. Resolve the missing components.
  6. Click OK.
  7. Expand CMSIS group in the Project window:
  8. Open RTX_Config.c and adapt configuration to suit the application including:
    • System Configuration->Global Dynamic Memory size
    • Kernel Tick Frequency
    • Thread Configuration->Default Thread Stack size
    • Details are found in Configure RTX v5
  9. Rename function int main (void) to void app_main (void *arg). Create new function int main (void) which implements at least:
    • System initialization and configuration
    • Update SystemCoreClock
    • Initialize CMSIS-RTOS kernel
    • Creates new thread app_main
    • Start RTOS scheduler

Example - Application Main Thread

/* Renamed main() function */
void app_main (void *arg) {
while (1) {
/* .. */
;
}
}
/* New main function to start app_main */
int main (void) {
Init_Hardware();
// System Initialization
SystemCoreClockUpdate();
// ...
osKernelInitialize(); // Initialize CMSIS-RTOS
osThreadNew(app_main, NULL, NULL); // Create application main thread
osKernelStart(); // Start thread execution
}
while(1);
}
Note
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 1000Hz in the System Configuration.

To validate the correct operation of your RTOS after migration you can temporarily integrate the RTOS Validation component into your project.

Level 2 Migration - Use API v2 and v1 alongside in RTX5

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.

The component selection is identical to Migration Level 1.

Include "cmsis_os2.h" in all modules where access to API v2 functions is required.

#include "cmsis_os.h" // ARM::CMSIS:RTOS:Keil RTX5
#include "cmsis_os2.h" // ARM::CMSIS:RTOS2:Keil RTX5

The following snippet shows how threads - created with both API versions - live along-side:

/*----------------------------------------------------------------------------
* Thread 4 'phaseD': Phase D output - API v2 thread
*---------------------------------------------------------------------------*/
void phaseD (void *argument) {
for (;;) {
osThreadFlagsWait(0x0001, osFlagsWaitAny, osWaitForever); /* wait for an event flag 0x0001 */
Switch_On (LED_D);
signal_func(tid_phaseA); /* call common signal function */
Switch_Off(LED_D);
}
}
/*----------------------------------------------------------------------------
* Thread 5 'clock': Signal Clock - API v1 thread
*---------------------------------------------------------------------------*/
void clock (void const *argument) {
for (;;) {
osSignalWait(0x0100, osWaitForever); /* Wait for event send by API v2 function osThreadFlagsSet() */
Switch_On (LED_CLK);
osDelay(80); /* delay ticks */
Switch_Off(LED_CLK);
}
}
/* Define the API v1 thread */
osThreadDef(clock, osPriorityNormal, 1, 0);
/*----------------------------------------------------------------------------
* Main: Initialize and start RTX Kernel
*---------------------------------------------------------------------------*/
void app_main (void *argument) {
; //...
/* Create the API v2 thread */
tid_phaseD = osThreadNew(phaseD, NULL, NULL);
/* Create the API v1 thread */
tid_clock = osThreadCreate(osThread(clock), NULL);
osThreadFlagsSet(tid_phaseA, 0x0001); /* set signal to phaseA thread */
while(1);
}

The full example "RTX5 Migration" is part of the CMSIS5 pack and available from the pack installer.

Level 3 Migration - Full transition to API v2

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:

  1. Open Manage Run-Time Environment window:
  2. Expand CMSIS Software Component:
  3. Expand RTOS (API) Software Component and de-select Keil RTX5
  4. Click OK
  5. Remove all occurances of
    #include "cmsis_os.h"
  6. 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.
Note
See Detailed API Function Differences for details in differences.

Generally there are now longer os*Def macros to declare OS objects.

Note
Signal Events have been replaced. Use the functions listed under Thread Flags and Event Flags instead.
The Mail Queue RTOS v1 functions have been deprecated. Use the functionality of the Message Queue instead. Differences are listed under Message Queue.