CMSIS-RTOS: Create an RTX Project

| CMSIS-RTOS Version 1.03 Real-Time Operating System: API and RTX Reference Implementation.

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Create an RTX Project

Example projects using CMSIS-RTOS RTX are available for various development boards. To make use of these examples, you need to install a Device Family Pack in µVision and use Pack Installer to open a CMSIS-RTOS Blinky project. If you wish to start a CMSIS-RTOS RTX from scratch, follow these steps:

- Create a new project and select a device.

- In the Manage Run-Time Environment window that opens, select CMSIS::CORE and CMSIS::RTOS (API)::Keil RTX. If the Validation Output requires other components to be present, try to use the Resolve button:

- Click OK. In the Project window, you will see the files that have been automatically added to you project, such as RTX_Conf_CM.c and the system and startup files:

- You can add template files to the project by right-clicking on Source Group 1 and selecting Add New Item to 'Source Group 1'. In the new window, click on User Code Template. On the right-hand side you will see all available template files for CMSIS-RTOS RTX:

- Finally, configure RTX to the application's needs using the RTX_Conf_CM.c file.

# Define and Reference Object Definitions

With `#define` `osObjectsExternal` objects are defined as external symbols. This allows to create a consistent header file that is used throughout a project. If you are using the CMSIS-RTOS 'main' function user code template, such a header file (called `osObjects.h`) will be added automatically to the project:

Code Example

/*----------------------------------------------------------------------------
* osObjects.h: CMSIS-RTOS global object definitions for an application
*----------------------------------------------------------------------------
* This header file defines global RTOS objects used throughout a project
* #define osObjectsPublic indicates that objects are defined; without that
* definition the objects are defined as external symbols.
*--------------------------------------------------------------------------*/
#ifndef __osObjects
#define __osObjects
#if (!defined (osObjectsPublic))
#define osObjectsExternal // define RTOS objects with extern attribute
#endif
#include <cmsis_os.h> // CMSIS RTOS header file
// global 'thread' functions -------------------------------------------------
extern void thread_sample (void const *argument); // function prototype
osThreadDef (thread_sample, osPriorityBelowNormal, 1, 100);
// global 'memory pools' -----------------------------------------------------
osPoolDef(MyPool, 10, long);
#endif // __osObjects

This header file defines all objects when included in a C/C++ source file. When `#define` `osObjectsExternal` is present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be used throughout the whole project.

Code Example

#include "osObjects.h" // Definition of the CMSIS-RTOS objects

# Using IRQ Interrupts

The CMSIS-RTOS RTX kernel uses the following interrupts:

- Timer interrupt (SysTick or alternative peripheral timer) to generate periodic timer ticks
- SVC (Supervisor Call) when calling the majority of RTX functions from Thread mode
- PendSV (request for system-level service) when calling certain RTX functions from Handler mode

Interrupts can be used without limitation. Interrupt priority grouping can be used with some restrictions:

- IRQ interrupts are never disabled by RTX Kernel for ARMv7-M architectures (Cortex-M3/M4/M7).
- Software interrupt 0 is used by RTX and cannot be used in an application.
- RTX uses its own SVC Handler which is automatically linked from the library. SVC Functions explains how to use a custom SVC table.
- When interrupt priority grouping is used, the PRIGROUP must be set before the osKernelInitialize() function is called (usually in the SystemInit() function in the system_device.c file). The kernel reads the value of PRIGROUP to correctly set internal interrupt pre-emption priorities.
- Allowed values for PRIGROUP are from 0 to 6. The PRIGROUP value 7 will cause RTX to fail.
- The lowest two pre-emption priorities are reserved for RTX kernel, all remaining pre-emption priorities are available to be used in an application.
- Do not change the priority used by the RTX kernel. If this cannot be avoided, ensure that the preempt priority of SysTick/PendSV is lower than SVC.
- Check the main stack size configured from the device startup file if you see sporadic crashes of your application. Supervisor Calls (SVCs) are used when calling RTX functions from Thread mode. All SVC calls use the main stack.