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.
Only a few incompatibilities and limitations exist:
- Kernel startup
- The function
osKernelRunning
has been removed in CMSIS-RTOS v2, use osKernelGetState() instead.
- Function
main
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 osKernelInitialize() and must be started by calling osKernelStart().
- OS tick
RTX5 uses the OS Tick API to configure the tick interrupts. The interval calculation is typically based on SystemCoreClock
variable. Thus one has to assure this variable is set correctly before calling osKernelStart.
- The function
osWait
is deprecated.
- Error code incompatibility
CMSIS-RTOS v1 used two different error codes for invalid parameters: osErrorParameter
and osErrorValue
. The new version only uses a common osErrorParameter code. Therefore, code relying on osErrorValue is not compatible. The following functions are affected:
- The osDelay return code has changed from osErrorTimeout to osOK.
The level of migration depends on the project's phase in its life cycle:
- The first level of migration is to migrate to RTX5 without changing the API level.
- The second level in the transition is to use v2 API functions and v1 API functions in mixed variation.
- The third level 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.
Level 1 Migration - Upgrade to RTX5 on API v1
Upgrade to RTX Version 5 from any 4.x version using the API v1 compatibility layer. Configure an existing project as follows:
- Open Manage Run-Time Environment window
- Expand CMSIS software component.
- Expand RTOS (API), uncheck Keil RTX, and select Keil RTX5.
- Expand RTOS2 (API) and select Keil RTX5.
- Resolve missing components.
Component Selection for RTX5
- Click OK.
- Expand CMSIS group in the Project window:
- Open RTX_Config.h and adapt the configuration to suit the application including (refer to Configure RTX v5):
- System Configuration->Global Dynamic Memory size
- Kernel Tick Frequency
- Thread Configuration->Default Thread Stack size
- Rename function
int main (void)
to void app_main (void *arg)
.
- Create a 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
#include "RTE_Components.h"
#include CMSIS_device_header
void app_main (void const *argument) {
}
int main (void) {
SystemCoreClockUpdate();
osThreadCreate(osThread(app_main), NULL);
for (;;);
}
- 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 1000 Hz 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.
The following snippet shows how threads - created with both API versions - live along-side:
void phaseD (void *argument) {
for (;;) {
Switch_On (LED_D);
signal_func(tid_phaseA);
Switch_Off(LED_D);
}
}
void clock (void const *argument) {
for (;;) {
Switch_On (LED_CLK);
Switch_Off(LED_CLK);
}
}
void app_main (void *argument) {
;
tid_clock = osThreadCreate(osThread(clock), NULL);
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:
- Open Manage Run-Time Environment window:
- Expand CMSIS Software Component:
- Expand RTOS (API) Software Component and de-select Keil RTX5
- Click OK
- Exchange all occurrences of with
- 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 no 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.