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
Thread Configuration

The CMSIS-RTOS RTX provides several parameters to configure the Thread Management functions.

Configuration of Thread Count and Stack Space

The CMSIS-RTOS RTX kernel uses a separate stack space for each thread and provides two methods for defining the stack requirements:

osThreadAttr_t is a parameter of the function osThreadNew.

Note
Before the RTX kernel is started by the osKernelInitialize() function, the main stack defined in startup_device.s is used. The main stack is also used for:
  • user application calls to RTX functions in Thread mode using SVC calls
  • interrupt/exception handlers.

Stack Overflow Checking

RTX5 implements a software stack overflow checking that traps stack overruns. Stack is used for return addresses and automatic variables and extensive usage or incorrect stack configuration may cause a stack overflow. Software stack overflow checking is controlled with the define OS_STACK_CHECK.

If a stack overflow is detected, the function os_Error with error code os_ErrorStackUnderflow is called. By default, this function is implemented as endless loop and will practically stop code execution.

Stack Usage Watermark

RTX5 initializes thread stack with watermark pattern (0xCC) when a thread is created. This allows the debugger to determine maximum stack usage for each thread. It is typically used during development but removed from the final application. Stack usage watermark is controlled with the define OS_STACK_WATERMARK.

Enabling this option significantly increases the execution time of osThreadNew (depends on thread stack size).

Processor Mode for Thread Execution

RTX5 allows to execute threads in unprivileged or privileged processor mode. The processor mode is controlled with the define OS_PRIVILEGE_MODE.

In unprivileged processor mode, the software:

  • has limited access to the MSR and MRS instructions, and cannot use the CPS instruction.
  • cannot access the system timer, NVIC, or system control block.
  • might have restricted access to memory or peripherals. In privileged processor mode the software can use all the instructions and has access to all resources.

Thread Configuration Options

config_wizard_threads.png
RTX_Config.c: Thread Configuration


Option #define Description
Object specific Memory allocation OS_THREAD_OBJ_MEM Enables object specific memory allocation. See Object-specific Memory Pools.
Number of user Threads (total) OS_THREAD_NUM Defines maximum number of user threads that can be active at the same time. Applies to user threads with system provided memory for control blocks. Default value is 1. Value range is [1-1000].
Number of user Threads with user-provided Stack size OS_THREAD_USER_STACK_NUM Defines maximum number of user threads with user-provided stack size. Default value is 0. Value range is [0-1000].
Total Stack size [bytes] for user Threads with user-provided Stack size OS_THREAD_USER_STACK_SIZE Defines the combined stack size for user threads with user-provided stack size. Default value is 0. Value range is [0-1073741824] Bytes, in multiples of 8.
Default Thread Stack size [bytes] OS_STACK_SIZE Defines stack size for threads with zero stack size specified. Default value is 200. Value range is [96-1073741824] Bytes, in multiples of 8.
Idle Thread Stack size [bytes] OS_IDLE_THREAD_STACK_SIZE Defines stack size for Idle thread. Default value is 200. Value range is [72-1073741824] bytes, in multiples of 8.
Stack overrun checking OS_STACK_CHECK Enable stack overrun checks at thread switch.
Stack usage watermark OS_STACK_WATERMARK Initialize thread stack with watermark pattern for analyzing stack usage. Enabling this option increases significantly the execution time of thread creation.
Processor mode for Thread execution OS_PRIVILEGE_MODE Controls the processor mode. Default value is Privileged mode. Value range is [0=Unprivileged; 1=Privileged] mode.