/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \mainpage The CMSIS-RTOS manages the resources of the microcontroller system and implements the concept of parallel threads that run concurrently. There are many advantages of using an CMSIS-RTOS v2 compliant kernel as it provides a standardized interface. Applications frequently require several concurrent activities. CMSIS-RTOS can manage multiple concurrent activities at the time when they are needed. Each activity gets a separate thread which executes a specific task and this simplifies the overall program structure. The CMSIS-RTOS system is scalable and additional threads can be added easily at a later time. Threads have a priority allowing faster execution of time-critical parts of an user application. The CMSIS-RTOS offers services needed in many real-time applications, for example, periodical activation of timer functions, memory management, and message exchange between threads with time limits. The CMSIS-RTOS API v2 addresses the following new requirements: - Dynamic object creation no longer requires static memory, static memory buffers are now optional. - Support for ARMv8-M architecture that provides a Secure and Non-Secure state of code execution. - Provisions for message passing in multi-core systems. - Full support of C++ run-time environments. - C interface which is binary compatible across ABI compatible compilers. As a consequence of these requirements the CMSIS-RTOS API v2 has the following fundamental modifications: - The functions osXxxxNew replace osXxxxCreate functions; osXxxxNew and osXxxxDelete create and destroy objects. - The C function main is not longer started as a thread (this was an optional feature in CMSIS-RTOS v1). - Functions that return osEvent have been replaced. CMSIS-RTOS API v2 provides an translation layer for the CMSIS-RTOS API v1. It is possible to intermix CMSIS-RTOS API v2 and CMSIS-RTOS API v1 within the same application. You may migrate overtime to the new API as explained in \ref os2Migration. CMSIS-RTOS API v2 is not POSIX compliant, but has provisions to enable a POSIX translation layer and a C++ interface. \todo Investigate into a flexible C++ interface and potential POSIX translation
CMSIS-RTOS in ARM::CMSIS Pack ----------------------------- The following files relevant to CMSIS-RTOS are present in the ARM::CMSIS Pack directories: File/Folder | Content -----------------------------|------------------------------------------------------------------------ \b CMSIS/Documentation/RTOS2 | This documentation \b CMSIS/Documentation/RTOS | CMSIS-RTOS API v1 documentation \b CMSIS/RTOS2/Include | \ref cmsis_os2_h */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page rtos_revisionHistory Revision History
Version Description
V2.00 Alpha - Kernel:\n -- added: osKernelGetInfo, osKernelGetState.\n -- added: osKernelLock, osKernelUnlock.\n -- added: osKernelSuspend, osKernelResume.\n -- added: osKernelGetTime.\n -- renamed osKernelSysTick to osKernelGetSysTick.\n - Thread:\n -- extended number of thread priorities.\n -- changed thread return value.\n -- replaced osThreadCreate with osThreadNew.\n -- added: osThreadGetState.\n -- added: osThreadSuspend, osThreadResume.\n -- added: osThreadJoin, osThreadDetach, osThreadExit.\n - Signals:\n -- renamed osSignals to osThreadFlags.\n -- changed return value of Set/Clear/Wait functions.\n -- Clear function limited to current running thread.\n -- extended Wait function (options).\n -- added: osThreadFlagsGet.\n - Event Flags: added new independent object for handling Event Flags.\n - Delay and Wait functions:\n -- added: osDelayUntil.\n -- deprecated: osWait.\n - Timer:\n -- replaced osTimerCreate with osTimerNew.\n -- added: osTimerIsRunning.\n - Mutex:\n -- extended: attributes (Recursive, Priority Inherit, Robust).\n -- replaced osMutexCreate with osMutexNew.\n -- renamed osMutexWait to osMutexAcquire.\n -- added: osMutexGetOwner.\n - Semaphore:\n -- extended: maximum and initial token count.\n -- replaced osSemaphoreCreate with osSemaphoreNew.\n -- renamed osSemaphoreWait to osSemaphoreAcquire (changed return value).\n -- added: osSemaphoreGetCount.\n - Memory Pool:\n -- using osMemoryPool prefix instead of osPool.\n -- replaced osPoolCreate with osMemoryPoolNew.\n -- extended: osMemoryPoolAlloc (timeout).\n -- added: osMemoryPoolGetCapacity, osMemoryPoolGetBlockSize.\n -- added: osMemoryPoolGetCount, osMemoryPoolGetSpace.\n -- added: osMemoryPoolDelete.\n -- deprecated: osPoolCAlloc.\n - Message Queue:\n -- fixed size messages instead of a single 32-bit values.\n -- using osMessageQueue prefix instead of osMessage.\n -- replaced osMessageCreate with osMessageQueueNew.\n -- updated: osMessageQueuePut, osMessageQueueGet.\n -- added: osMessageQueueGetCapacity, osMessageQueueGetMsgSize.\n -- added: osMessageQueueGetCount, osMessageQueueGetSpace.\n -- added: osMessageQueueReset, osMessageQueueDelete.\n - Mail Queue: deprecated (superseded by extended Message Queue functionality).\n
V1.02 - only documentation changes Added: Overview of the \ref rtosValidation "CMSIS-RTOS Validation" Software Pack.\n Clarified: Behavior of \ref CMSIS_RTOS_TimeOutValue.
V1.02 Added: New control functions for short timeouts in microsecond resolution \b osKernelSysTick, \b osKernelSysTickFrequency, \b osKernelSysTickMicroSec.\n Removed: osSignalGet.
V1.01 Added capabilities for C++, kernel initialization and object deletion.\n Prepared for C++ class interface. In this context to \em const attribute has been moved from osXxxxDef_t typedefs to the osXxxxDef macros.\n Added: \ref osTimerDelete, \ref osMutexDelete, \ref osSemaphoreDelete.\n Added: \ref osKernelInitialize that prepares the Kernel for object creation.\n
V1.00 First official Release.\n Added: \ref osKernelStart; starting 'main' as a thread is now an optional feature.\n Semaphores have now the standard behavior.\n \b osTimerCreate does no longer start the timer. Added: \ref osTimerStart (replaces osTimerRestart).\n Changed: osThreadPass is renamed to \ref osThreadYield.
V0.02 Preview Release.
*/ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page functionOverview Function Overview CMSIS-RTOS v2 provides multiple API interfaces: - \subpage rtos_api2 is the new C function API that supports dynamic object creation, ARMv8-M, and multi-processor communication. - CMSIS-RTOS C API v1 is a C function API the is backward compatible with CMSIS-RTOS v1. - \subpage rtos_apicpp is a C++ class function API. It is possible to intermix the different API variants in the same application and even in the same C/C++ source module. However, the functions of the C API Version 1 may be deprecated in future versions of CMSIS-RTOS. \section CMSIS_RTOS_TimeOutValue Timeout Value Timeout values are an argument to several \b osXxx functions to allow time for resolving a request. A timeout value of \b 0 means that the RTOS does not wait and returns instantly, even when no resource is available. A timeout value of \ref osWaitForever means that the RTOS waits infinite until a resource becomes available. The timeout value specifies the number of timer ticks until the time delay elapses. The value is an upper bound and depends on the actual time elapsed since the last timer tick. Examples: - timeout value \b 0 : the system does not wait, even when no resource is available the RTOS function returns instantly. - timeout value \b 1 : the system waits until the next timer tick occurs; depending on the previous timer tick, it may be a very short wait time. - timeout value \b 2 : actual wait time is between 1 and 2 timer ticks. - timeout value \ref osWaitForever : system waits infinite until a resource becomes available. \todo B: remove first '|' to make the picture clearer, make ... before first tick, add word 'time' after the arrow. \image html TimerValues.png "Timer Values" \section CMSIS_RTOS_ISR_Calls Calls from Interrupt Service Routines The following CMSIS-RTOS2 functions can be called from threads and Interrupt Service Routines (ISR): - \ref osThreadFlagsSet - \ref osEventFlagsSet, \ref osEventFlagsClear, \ref osEventFlagsGet, \ref osEventFlagsWait - \ref osSemaphoreAcquire, \ref osSemaphoreRelease, \ref osSemaphoreGetCount - \ref osMemoryPoolAlloc, \ref osMemoryPoolFree, \ref osMemoryPoolGetCapacity, \ref osMemoryPoolGetBlockSize, \ref osMemoryPoolGetCount, \ref osMemoryPoolGetSpace - \ref osMessageQueuePut, \ref osMessageQueueGet, \ref osMessageQueueGetCapacity, \ref osMessageQueueGetMsgSize, \ref osMessageQueueGetCount, \ref osMessageQueueGetSpace Functions that cannot be called from an ISR are verifying the interrupt status and return, in case they are called from an ISR context, the status code \b osErrorISR. In some implementations, this condition might be caught using the HARD FAULT vector. */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page rtos_api2 CMSIS-RTOS C API v2 Overview of all CMSIS-RTOS C API v2 functions. - \ref CMSIS_RTOS_KernelCtrl - \ref osKernelGetInfo : \copybrief osKernelGetInfo - \ref osKernelGetState : \copybrief osKernelGetState - \ref osKernelGetTick : \copybrief osKernelGetTick - \ref osKernelGetTime : \copybrief osKernelGetTime - \ref osKernelInitialize : \copybrief osKernelInitialize - \ref osKernelLock : \copybrief osKernelLock - \ref osKernelResume : \copybrief osKernelResume - \ref osKernelStart : \copybrief osKernelStart - \ref osKernelSuspend : \copybrief osKernelSuspend - \ref osKernelTickMicroSec : \copybrief osKernelTickMicroSec - \ref osKernelUnlock : \copybrief osKernelUnlock - \ref CMSIS_RTOS_ThreadMgmt - \ref osThreadDetach : \copybrief osThreadDetach - \ref osThreadExit : \copybrief osThreadExit - \ref osThreadGetId : \copybrief osThreadGetId - \ref osThreadGetPriority : \copybrief osThreadGetPriority - \ref osThreadGetState : \copybrief osThreadGetState - \ref osThreadJoin : \copybrief osThreadJoin - \ref osThreadNew : \copybrief osThreadNew - \ref osThreadResume : \copybrief osThreadResume - \ref osThreadSetPriority : \copybrief osThreadSetPriority - \ref osThreadSuspend : \copybrief osThreadSuspend - \ref osThreadTerminate : \copybrief osThreadTerminate - \ref osThreadYield : \copybrief osThreadYield - \ref CMSIS_RTOS_Wait - \ref osDelay : \copybrief osDelay - \ref osDelayUntil : \copybrief osDelayUntil - \ref CMSIS_RTOS_TimerMgmt - \ref osTimerDelete : \copybrief osTimerDelete - \ref osTimerIsRunning : \copybrief osTimerIsRunning - \ref osTimerNew : \copybrief osTimerNew - \ref osTimerStart : \copybrief osTimerStart - \ref osTimerStop : \copybrief osTimerStop - \ref CMSIS_RTOS_EventFlags - \ref osEventFlagsNew : \copybrief osEventFlagsNew - \ref osEventFlagsDelete : \copybrief osEventFlagsDelete - \ref osEventFlagsSet : \copybrief osEventFlagsSet - \ref osEventFlagsClear : \copybrief osEventFlagsClear - \ref osEventFlagsGet : \copybrief osEventFlagsGet - \ref osEventFlagsWait : \copybrief osEventFlagsWait - \ref CMSIS_RTOS_ThreadFlagsMgmt - \ref osThreadFlagsSet : \copybrief osThreadFlagsSet - \ref osThreadFlagsClear : \copybrief osThreadFlagsClear - \ref osThreadFlagsGet : \copybrief osThreadFlagsGet - \ref osThreadFlagsWait : \copybrief osThreadFlagsWait - \ref CMSIS_RTOS_Message - \ref osMessageQueueDelete : \copybrief osMessageQueueDelete - \ref osMessageQueueGet : \copybrief osMessageQueueGet - \ref osMessageQueueGetCapacity : \copybrief osMessageQueueGetCapacity - \ref osMessageQueueGetCount : \copybrief osMessageQueueGetCount - \ref osMessageQueueGetMsgSize : \copybrief osMessageQueueGetMsgSize - \ref osMessageQueueGetSpace : \copybrief osMessageQueueGetSpace - \ref osMessageQueueNew : \copybrief osMessageQueueNew - \ref osMessageQueuePut : \copybrief osMessageQueuePut - \ref osMessageQueueReset : \copybrief osMessageQueueReset - \ref CMSIS_RTOS_PoolMgmt - \ref osMemoryPoolAlloc : \copybrief osMemoryPoolAlloc - \ref osMemoryPoolDelete : \copybrief osMemoryPoolDelete - \ref osMemoryPoolFree : \copybrief osMemoryPoolFree - \ref osMemoryPoolGetBlockSize : \copybrief osMemoryPoolGetBlockSize - \ref osMemoryPoolGetCapacity : \copybrief osMemoryPoolGetCapacity - \ref osMemoryPoolGetCount : \copybrief osMemoryPoolGetCount - \ref osMemoryPoolGetSpace : \copybrief osMemoryPoolGetSpace - \ref osMemoryPoolNew : \copybrief osMemoryPoolNew - \ref CMSIS_RTOS_MutexMgmt - \ref osMutexAcquire : \copybrief osMutexAcquire - \ref osMutexDelete : \copybrief osMutexDelete - \ref osMutexGetOwner : \copybrief osMutexGetOwner - \ref osMutexNew : \copybrief osMutexNew - \ref osMutexRelease : \copybrief osMutexRelease - \ref CMSIS_RTOS_SemaphoreMgmt - \ref osSemaphoreAcquire : \copybrief osSemaphoreAcquire - \ref osSemaphoreDelete : \copybrief osSemaphoreDelete - \ref osSemaphoreGetCount : \copybrief osSemaphoreGetCount - \ref osSemaphoreNew : \copybrief osSemaphoreNew - \ref osSemaphoreRelease : \copybrief osSemaphoreRelease */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page rtos_apicpp CMSIS-RTOS C++ API Coming soon */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page cmsis_os2_h Header File: cmsis_os2.h The file \b cmsis_os2.h is a standard header file that interfaces to every CMSIS-RTOS API v2 compliant Real-Time Operating Systems (RTOS). Each implementation is provided the same cmsis_os2.h which defines the interface to the \ref rtos_api2. Using the \b cmsis_os2.h along with dynamic object allocation allows to create source code or libraries that require no modifications when using on a different CMSIS-RTOS v2 implementation. Header file %cmsis_os2.h \include cmsis_os2.h */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page rtx5_impl RTX v5 Implementation The RTX version 5 implements the CMSIS-RTOS API v2 as native RTOS interface for Cortex-M processor-based devices. A translation layer to CMSIS-RTOS API v1 is provided and with minimal effort RTX version 5 can be used in applications that where previously based on RTX version 4 and CMSIS-RTOS v1. The following sections provide further details: - \subpage theory_op : provides general information about the operation of RTX version 5. - \subpage cre_rtx_proj - \subpage config_rtx */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page theory_op Theory of Operation This section describes how RTX version 5 manages the resources of the target system. Many aspects of the kernel are configurable and the configuration options are mentioned where applicable. \section KernelTimer RTX Kernel Timer Tick and Thread Management By default, CMSIS-RTOS RTX5 uses the Cortex-M SysTick timer to generate periodic interrupts for the RTX kernel timer tick. CMSIS-RTOS provides \ref CMSIS_RTOS_TimerMgmt functions and several CMSIS-RTOS functions have a timeout parameter. This periodic RTX kernel timer tick interrupt is used to derive the required time interval. CMSIS-RTOS RTX also provides configuration options for a alternative timer and tick-less operation. To handle timeout and time delays for threads, the CMSIS-RTOS RTX thread management is controlled by the RTX kernel timer tick interrupt. The thread context contains all CPU registers (R0 - R12), the return address (LR), the program counter (PC), and the processor status register (xPSR). For the Cortex-M4 FPU and Cortex-M7 FPU the floating point status and registers (S0 - S32, FPSCR) are also part of the thread context. When a thread switch occurs: - the thread context of the current running thread is stored on the local stack of this thread. - the stack pointer is switched to the next running thread. - the thread context of this next running thread is restored and this thread starts to run. \note - For Cortex-M0, Cortex-M3, Cortex-M4, and Cortex-M7 the thread context requires 64 bytes on the local stack. - For Cortex-M4 FPU and Cortex-M7 FPU the thread context requires 200 bytes on the local stack. For devices with Cortex-M4 FPU and Cortex-M7 FPU the default stack space should be increased to a minimum of 300 bytes. Each thread is provided with an separate stack that holds the thread context and stack space for automatic variables and return addresses for function call nesting. The stack sizes of the RTX threads are flexible configurable as explained in the section \ref threadConfig. RTX even offers a configurable checking for stack overflows and stack utilization. \section MemoryAllocation Variants of Memory Allocation The RTX objects threads, mutexes, semaphores, timers, messages, events and memory pools require dedicated RAM memory everytime they are created. RTX5 offers three different allocation mechanisms. If no specific method is configured or used osobjectNew()calls always default to the Global Dynamic Memory Pool. \subsection MemoryAllocationGlobal Global Dynamic Memory Pool \image html MemAllocGlob.png "Global Memory Pool for all objects" The global memory pool allocates all objects from a single large memory pool when an object is created. This method is often selected when object instances of arbitrary type and count are created at run-time. In case of insufficient memory the creation of an object instance can fail. This requires proper handling of \ref osErrorNoMemory returned by osobjectNew() functions. Enabled in \ref systemConfig. \subsection MemoryAllocationObject Object-specific Dynamic Memory Pools \image html MemAllocSpec.png "One memory pool per object type" Object-specific memory pools allows to reserve pools specific to a type of object, e.g: mutexes or threads. This is less flexible than a large single pool, but does provide advantages. e.g.: - Simplifies analysis of memory usage and handling of out-of-memory situations. - Allows dynamic memory management for specific object types only, while others might be allocated statically. - Map pools to different memory spaces (e.g. for systems with different speed grades of RAM memory) Enabled in \ref threadConfig for thread objects.
Enabled in \ref timerConfig for timer objects.
Enabled in \ref eventFlagsConfig for event objects.
Enabled in \ref mutexConfig for mutex objects.
Enabled in \ref semaphoreConfig for semaphore.
Enabled in \ref memPoolConfig for memory pools.
Enabled in \ref msgQueueConfig for message objects.
\subsection MemoryAllocationStatic Static Memory Allocation \image html MemAllocStat.png "Statically allocated memory for all objects" In contrast to the dynamic memory allocations the static memory allocation requires compile-time allocation of object memory. This memory is reserved by the user application. e.g. by declaring a global array of the proper size for each object. Although this method is less flexible it has advantages. Mainly it removes the likelyhood of an \ref osErrorNoMemory when instancing a new object and avoids memory fragmentation. Most functional safety standards (like IEC61508) do not allow dynamic memory management or make the use of it very difficult. The following example shows how to create an OS object with static memory. \b Example: \code /*---------------------------------------------------------------------------- * CMSIS-RTOS 'main' function template *---------------------------------------------------------------------------*/ #include "RTE_Components.h" #include CMSIS_device_header #include "cmsis_os2.h" //include rtx_os.h for types of RTX objects #include "rtx_os.h" //The thread function instanced in this example void *worker(void *arg) { //work osDelay(10000); return 0; } // Define objects that are statically allocated for worker threads 1 and 2 os_thread_t worker_thread_tcb_1; os_thread_t worker_thread_tcb_2; // Reserve two areas for the stacks of worker threads 1 and 2 // uint64_t makes sure the memory alignment is 8 uint64_t worker_thread_stk_1[64]; uint64_t worker_thread_stk_2[64]; // Define the attributes which are used for thread creation // Optional const saves RAM memory and includes the values in periodic ROM tests const osThreadAttr_t worker_attr_1 = { "wrk1", osThreadJoinable, &worker_thread_tcb_1, sizeof(worker_thread_tcb_1), &worker_thread_stk_1[0], sizeof(worker_thread_stk_1), osPriorityAboveNormal, 0 }; const osThreadAttr_t worker_attr_2 = { "wrk2", osThreadJoinable, &worker_thread_tcb_2, sizeof(worker_thread_tcb_2), &worker_thread_stk_2[0], sizeof(worker_thread_stk_2), osPriorityAboveNormal, 0 }; // Define ID objects for threads osThreadId_t th1; osThreadId_t th2; /*---------------------------------------------------------------------------- * Application main thread *---------------------------------------------------------------------------*/ void *app_main (void *argument) { uint32_t param = NULL; //Create an instance of the worker thread with static resources (TCB and stack) th1 = osThreadNew(worker, ¶m, &worker_attr_1); //Create an instance of the worker thread with static resources th2 = osThreadNew(worker, ¶m, &worker_attr_2); //wait until worker thread 1 is terminated (void) osThreadJoin(th1, NULL); //wait until worker thread 2 is terminated (void) osThreadJoin(th2, NULL); for (;;) {} } int main (void) { // System Initialization SystemCoreClockUpdate(); // ... osKernelInitialize(); // Initialize CMSIS-RTOS osThreadNew(app_main, NULL, NULL); // Create application main thread osKernelStart(); // Start thread execution for (;;) {} } \endcode */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page cre_rtx_proj 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-RTOS2 Blinky project. If you wish to start a CMSIS-RTOS RTX5 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\::RTOS2 (API)\::Keil RTX5. If the Validation Output requires other components to be present, try to use the \b Resolve button: \image html manage_rte_output.png - Click \b OK. In the \b Project window, you will see the files that have been automatically added to you project, such as \b %RTX_Config.c and the system and startup files: \image html project_window.png - 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: \image html add_item.png - Finally, \ref config_rtx "configure" RTX to the application's needs using the \b %RTX_Config.c file. */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page config_rtx Configure RTX The file "RTX_Config.c" defines the configuration parameters of CMSIS-RTOS RTX and must be part of every project that is using the CMSIS-RTOS RTX kernel. The configuration file uses Configuration Wizard Annotations. Depending on the development tool, the annotations might lead to a more user-friendly graphical representation of the settings. The screenshot below shows the configuration file represented by the µVision Configuration Wizard: \image html config_wizard.png "RTX_Conf_CM.c in Configuration Wizard View" The configuration options are explained on these pages: - \subpage systemConfig - \subpage threadConfig - \subpage timerConfig - \subpage eventFlagsConfig - \subpage mutexConfig - \subpage semaphoreConfig - \subpage memPoolConfig - \subpage msgQueueConfig */ /* ========================================================================================================================== */ /** \page systemConfig System Configuration \image html config_wizard_system.png "RTX_Conf_CM.c: System Configuration" Name | \#define | Description ---------------------------------------|--------------------------|---------------------------------------------------------------- Global Dynamic Memory size [bytes] | \c OS_DYNAMIC_MEM_SIZE | Defines the combined global dynamic memory size. Default value is \token{4096}. Value range is \token{[0-1073741824]} bytes, in multiples of \token{8} bytes. Round-Robin Thread switching | \c OS_ROBIN_ENABLE | Enables Round-Robin Thread switching. Round-Robin Timeout [ms] | \c OS_ROBIN_TIMEOUT | Defines how long a thread will execute before a thread switch. Default value is \token{5}. Value range is \token{[1-1000]}. ISR FIFO Queue | \c OS_ISR_FIFO_QUEUE | RTOS Functions called from ISR store requests to this buffer. Default value is \token{16 entries}. Value range is \token{[4-256]} entries, stepping \token{4} entries. */ /* ========================================================================================================================== */ /** \page threadConfig Thread Configuration The CMSIS-RTOS RTX provides several parameters to configure threads. \section stackConfig Configuration of Thread count and Stack Space \ref osThreadAttr_t is passed to osThreadNew to set the options of a thread. CMSIS-RTOS RTX defines two methods for defining the stack requirements: - when \a *stack_mem in osThreadAttr_t is NULL, a fixed-size memory pool is used for the thread stack. In this case, \b OS_STKSIZE specifies the stack size for the thread function. - when \a *stack_mem specifies a memory location, the thread stack provided there. The size of this user space is specified with \b stack_size. Stack memory for threads is configured either statically by Static Resources - Number of Threads (total). Static memory in the size of Number of Threads * Default Thread Stack size is reserved. Alternatively the memory is allocated on demand from the Dynamic Resources pool (configured by System Configuration - Dynamic Resources - Memory size [bytes] for Stack). The CMSIS-RTOS RTX kernel uses a separate stack for each thread it creates. However, before the kernel is started by the \ref osKernelInitialize() function, the main stack size that is configured in the file startup_device.s is used. \image html config_wizard_threads.png "RTX_Conf_CM.c: Thread Configuration" Main stack is also used when: - the user application calls the majority of RTX functions from Thread mode (ending up in an SVC call) - running from handlers (user interrupt of exception handlers like SVCm PendSV, Faults, etc.) Name | \#define | Description ---------------------------------------------------------|------------------------|---------------------------------------------------------------- Object specific Memory allocation | \c OS_THREAD_OBJ_MEM | Enables object specific memory allocation. Number of user Threads (total) | \c 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 \token{6}. Value range is \token{[1-1000]}. Number of user Threads with user-provided Stack size | \c OS_THREAD_USER_STACK_NUM | Defines maximum number of user threads with user-provided stack size. Default value is \token{0}. Value range is \token{[0-1000]}. Total Stack size [bytes] for user Threads with user-provided Stack size | \c OS_THREAD_USER_STACK_SIZE | Defines the combined stack size for user threads with user-provided stack size. Default value is \token{0}. Value range is \token{[0-1073741824]} bits, sepping \token{8} bits. Default Thread Stack size [bytes] | \c OS_STACK_SIZE | Defines stack size for threads with zero stack size specified. Default value is \token{200}. Value range is \token{[96-1073741824]} bits, sepping \token{8} bits. Idle Thread Stack size [bytes] | \c OS_IDLE_THREAD_STACK_SIZE | Defines stack size for Idle thread. Default value is \token{200}. Value range is \token{[72-1073741824]} bits, sepping \token{8} bits. Stack overrun checking | \c OS_STACK_CHECK | Enable stack overrun checks at thread switch. Enabling this option increases slightly the execution time of a thread switch. If a stack overflow is detected at a thread switch, the function \b os_error with error code = 1 is called. By default, this function is implemented as endless loop and will practically stop code execution. Stack usage watermark | \c 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 | \c OS_PRIVILEGE_MODE | Controls the processor mode. Default value is \token{Privileged} mode. Value range is \token{[0=Unprivileged; 1=Privileged]} mode. */ /* ========================================================================================================================== */ /** \page timerConfig Timer Configuration \image html config_wizard_timer.png "RTX_Conf_CM.c: Timer Configuration" Name | \#define | Description ---------------------------------------|--------------------------|---------------------------------------------------------------- Object specific Memory allocation | \c OS_TIMER_OBJ_MEM | Enables object specific memory allocation. Number of Timer objects | \c OS_TIMER_NUM | Defines maximum number of objects that can be active at the same time. Applies to objects with system provided memory for control blocks. Value range is \token{[1-1000]}. Timer Thread Priority | \c OS_TIMER_THREAD_PRIO | Defines priority for timer thread. Default value is \token{40}. Value range is \token{[8-48]}, stepping \token{8}. The numbers have the following priority correlation: \token{8=Low}; \token{16=Below Normal}; \token{24=Normal}; \token{32=Above Normal}; \token{40=High}; \token{48=Realtime} Timer Thread Stack size [bytes] | \c OS_TIMER_THREAD_STACK_SIZE | Defines stack size for Timer thread. May be set to 0 when timers are not used. Default value is \token{200}. Value range is \token{[0-1073741824]}, stepping \token{8}. Timer Callback Queue entries | \c OS_TIMER_CB_QUEUE | Number of concurrent active timer callback functions. May be set to 0 when timers are not used. Default value is \token{4}. Value range is \token{[0-256]}. */ /* ========================================================================================================================== */ /** \page eventFlagsConfig Event Flags Configuration \image html config_wizard_eventFlags.png "RTX_Conf_CM.c: Event Flags Configuration" Name | \#define | Description ---------------------------------------|--------------------------|---------------------------------------------------------------- Object specific Memory allocation | \c OS_EVFLAGS_OBJ_MEM | Enables object specific memory allocation. Number of Event Flags objects | \c OS_EVFLAGS_NUM | Defines maximum number of objects that can be active at the same time. Applies to objects with system provided memory for control blocks. Value range is \token{[0-1000]}. */ /* ========================================================================================================================== */ /** \page mutexConfig Mutex Configuration \image html config_wizard_mutex.png "RTX_Conf_CM.c: Mutex Configuration" Name | \#define | Description ---------------------------------------|--------------------------|---------------------------------------------------------------- Object specific Memory allocation | \c OS_MUTEX_OBJ_MEM | Enables object specific memory allocation. Number of Mutex objects | \c OS_MUTEX_NUM | Defines maximum number of objects that can be active at the same time. Applies to objects with system provided memory for control blocks. Value range is \token{[0-1000]}. */ /* ========================================================================================================================== */ /** \page semaphoreConfig Semaphore Configuration \image html config_wizard_semaphore.png "RTX_Conf_CM.c: Semaphore Configuration" Name | \#define | Description ---------------------------------------|--------------------------|---------------------------------------------------------------- Object specific Memory allocation | \c OS_SEMAPHORE_OBJ_MEM | Enables object specific memory allocation. Number of Semaphore objects | \c OS_SEMAPHORE_NUM | Defines maximum number of objects that can be active at the same time. Applies to objects with system provided memory for control blocks. Value range is \token{[0-1000]}. */ /* ========================================================================================================================== */ /** \page memPoolConfig Memory Pool Configuration \image html config_wizard_memPool.png "RTX_Conf_CM.c: Memory Pool Configuration" Name | \#define | Description ---------------------------------------|--------------------------|---------------------------------------------------------------- Object specific Memory allocation | \c OS_MEMPOOL_OBJ_MEM | Enables object specific memory allocation. Number of Memory Pool objects | \c OS_MEMPOOL_NUM | Defines maximum number of objects that can be active at the same time. Applies to objects with system provided memory for control blocks. Value range is \token{[0-1000]}. Data Storage Memory size [bytes] | \c OS_MEMPOOL_DATA_SIZE | Defines the combined data storage memory size. Applies to objects with system provided memory for data storage. Default value is \token{0}. Value range is \token{[0-1073741824]}, stepping \token{4}. */ /* ========================================================================================================================== */ /** \page msgQueueConfig Message Queue Configuration \image html config_wizard_msgQueue.png "RTX_Conf_CM.c: Message Queue Configuration" Name | \#define | Description ---------------------------------------|--------------------------|---------------------------------------------------------------- Object specific Memory allocation | \c OS_MSGQUEUE_OBJ_MEM | Enables object specific memory allocation. Number of Message Queue objects | \c OS_MSGQUEUE_NUM | Defines maximum number of objects that can be active at the same time. Applies to objects with system provided memory for control blocks. Value range is \token{[0-1000]}. Data Storage Memory size [bytes] | \c OS_MSGQUEUE_DATA_SIZE | Defines the combined data storage memory size. Applies to objects with system provided memory for data storage. Default value is \token{0}. Value range is \token{[0-1073741824]}, stepping \token{4}. */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page rtosValidation RTOS Validation \note The test suite is available only for RTOS v1 API. ARM offers a Software Pack for the CMSIS-RTOS Validation. The ARM::CMSIS-RTOS_Validation Pack contains the following: - Source code of a CMSIS-RTOS Validation Suite along with configuration file. - Documentation of the CMSIS-RTOS Validation Suite. - Example that shows the usage of the CMSIS-RTOS Validation Suite using simulation. The CMSIS-RTOS Validation Suite is currently available in beta release and performs generic validation of various RTOS features. The test cases verify the functional behavior, test invalid parameters and call management functions from ISR. The following CMSIS-RTOS features can be tested with the current release: - Thread : Create multiple threads, terminate, restart, yield, change priority - Timer : Create periodic and one-shot timers - GenWait : Call generic wait functions (osDelay and osWait) - WaitFunc : Measure wait ticks (delay, mail, message, mutex, semaphore, signal) Moreover the following inter-thread communication functions can be tested: - Signal : Verify signal events - Memory Pool : Verify memory allocation - Message Queue : Exchange messages between threads - Mail Queue : Exchange data between threads - Mutex : Synchronize resource access - Semaphore : Access shared resources The RTOS Validation output can be printed to a console, output via ITM printf, or output to a memory buffer. \section test_output Sample Test Output \verbatim CMSIS-RTOS Test Suite Oct 21 2015 16:39:16 TEST 01: TC_ThreadCreate PASSED TEST 02: TC_ThreadMultiInstance PASSED TEST 03: TC_ThreadTerminate PASSED : : TEST 08: TC_ThreadChainedCreate PASSED TEST 09: TC_ThreadYield NOT EXECUTED TEST 10: TC_ThreadParam PASSED : : TEST 60: TC_MailFromISRToThread PASSED Test Summary: 60 Tests, 59 Executed, 59 Passed, 0 Failed, 0 Warnings. Test Result: PASSED \endverbatim */ /* ========================================================================================================================== */ // Group creation for Reference /** \addtogroup CMSIS_RTOS1 CMSIS-RTOS API v1 \brief This section describes the CMSIS-RTOS API v1. \details The CMSIS-RTOS is a generic API layer that interfaces to an existing RTOS kernel. CMSIS-RTOS API v2 provides an translation layer for the CMSIS-RTOS API v1 that simplifies migration. Refer to the Reference guide of the CMSIS-RTOS API v1 for details. */ // Group creation for Reference /** \addtogroup CMSIS_RTOS CMSIS-RTOS API v2 \brief This section describes the CMSIS-RTOS API v2. \details The CMSIS-RTOS is a generic API layer that interfaces to an existing RTOS kernel. */