RTOS2 Documentation Updates

[cmsis] / CMSIS / DoxyGen / RTOS2 / src / cmsis_os2.txt

/*=======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 <b>CMSIS-RTOS API v2</b> 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 <a class="el" href="http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html">ABI compatible compilers</a>.

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
<a class="el" href="../../RTOS/html/index.html">CMSIS-RTOS API v1</a>. 
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 C++11/C++14 interface.

<hr>

CMSIS-RTOS in ARM::CMSIS Pack
-----------------------------

The following files relevant to CMSIS-RTOS are present in the <b>ARM::CMSIS</b> 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

<table class="cmtable" summary="Revision History">
    <tr>
      <th>Version</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>V2.00 Alpha</td>
      <td>
        - 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
     </td>
    </tr>
    <tr>
      <td>V1.02 - only documentation changes</td>
      <td>
      Added: Overview of the \ref rtosValidation "CMSIS-RTOS Validation" Software Pack.\n
          Clarified: Behavior of \ref CMSIS_RTOS_TimeOutValue.
     </td>
    </tr>
    <tr>
      <td>V1.02</td>
      <td>Added: New control functions for short timeouts in microsecond resolution \b osKernelSysTick,
      \b osKernelSysTickFrequency, \b osKernelSysTickMicroSec.\n
      Removed: osSignalGet.
     </td>
    </tr>
    <tr>
      <td>V1.01</td>
      <td>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
      </td>
    </tr>
    <tr>
      <td>
      V1.00</td>
      <td>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.
      </td>
    </tr>
    <tr>
      <td>V0.02</td>
      <td>Preview Release.</td>
    </tr>
</table>
*/


/*=======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.
  - <a class="el" href="../../RTOS/html/functionOverview.html">CMSIS-RTOS C API v1</a> 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 <b>C API Version 1</b> 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 osKernelGetSysTimerCount : \copybrief osKernelGetSysTimerCount
   - \ref osKernelGetSysTimerFreq : \copybrief osKernelGetSysTimerFreq
   - \ref osKernelInitialize : \copybrief osKernelInitialize
   - \ref osKernelLock : \copybrief osKernelLock
   - \ref osKernelResume : \copybrief osKernelResume
   - \ref osKernelStart : \copybrief osKernelStart
   - \ref osKernelSuspend : \copybrief osKernelSuspend
   - \ref osKernelGetTickCount : \copybrief osKernelGetTickCount
   - \ref osKernelGetTickFreq : \copybrief osKernelGetTickFreq
   - \ref osKernelUnlock : \copybrief osKernelUnlock

 - \ref CMSIS_RTOS_ThreadMgmt
   - \ref osThreadDetach : \copybrief osThreadDetach
   - \ref osThreadExit : \copybrief osThreadExit
   - \ref osThreadGetName : \copybrief osThreadGetName
   - \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.

<b>Header file %cmsis_os2.h</b>

\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
<a href="http://www.keil.com/support/man/docs/gsac/GSAC_SYSTICKtimer.htm" target="_blank">SysTick</a> 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 Memory Allocation 

The RTX objects (thread, mutex, semaphore, timer, message, event and memory pool) require dedicated RAM memory.
Objects can be created using os<i>object</i>New() calls and deleted using os<i>object</i>Delete() calls. The related
object memory needs to be available during the life-time of the object.

RTX5 offers three different memory allocation methods for objects:

  - \ref GlobalMemoryPool uses a single global memory pool for all objects. It is easy to configure, but may have 
    the disadvantage for memory fragmentation when different object sizes are created and deleted.

  - \ref ObjectMemoryPool uses a fixed-size memory pool for each object type. The method is time deterministic
     and avoids memory fragmentation.

  - \ref StaticObjectMemory is reserved during the compile time and completely avoids that a system can be out of memory.
    This is required for some safety critical applications.
 
It possible to intermix the usage of the all memory allocation methods in the same application.


\subsection GlobalMemoryPool Global Memory Pool
\image html MemAllocGlob.png "Global Memory Pool for all objects"
The global memory pool allocates all objects from a one memory area.
This method of memory allocation is the default configuration setting of RTX5.

When pool does not provide sufficient memory the creation of the object fails and the related os<i>object</i>New() function returns \token{NULL}.

\todo refer to object counters once available

Enabled in \ref systemConfig.

\subsection ObjectMemoryPool Object-specific Memory Pools
\image html MemAllocSpec.png "One memory pool per object type"
Object-specific memory pools may be enabled for a selected object type, e.g: mutex or thread using the RTX configuration file:
 - Enabled in \ref threadConfig for thread objects.
 - Enabled in \ref timerConfig for timer objects.           <br> 
 - Enabled in \ref eventFlagsConfig for event objects.      <br> 
 - Enabled in \ref mutexConfig for mutex objects.           <br> 
 - Enabled in \ref semaphoreConfig for semaphore.           <br> 
 - Enabled in \ref memPoolConfig for memory pools.          <br> 
 - Enabled in \ref msgQueueConfig for message objects.      <br> 

This dedicated fixed-size memory pool ensures time deterministic behaviour and avoids memory fragmentation.
As the memory pool is specific to an object the handling of out-of-memory situations may be simplified.

When pool does not provide sufficient memory the creation of the object fails and the related os<i>object</i>New() function returns \token{NULL}.

\todo explain how to Map pools to different memory spaces (e.g. for systems with different speed grades of RAM memory)

\subsection StaticObjectMemory Static Object Memory
\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. 
The following example shows how to create an OS object using static memory.

<b> Code Example: </b> 
\code{.c}
/*----------------------------------------------------------------------------
 * 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)
{
  while(1) 
  {
    //work
        osDelay(10000);
  }  
}
 
// Define objects that are statically allocated for worker threads 1 and 2
os_thread_t worker_thread_tcb_1;
 
// 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];
 
// 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
};
 

// Define ID object for thread
osThreadId_t th1;
 
/*----------------------------------------------------------------------------
 * 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, &param, &worker_attr_1);
    
  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 <b>CMSIS\::CORE</b> and <b>CMSIS\::RTOS2 (API)\::Keil RTX5</b>.
  If the <b>Validation Output</b> 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 <b>Source Group 1</b> and selecting
  <b>Add New Item to 'Source Group 1'</b>. In the new window, click on <b>User Code Template</b>. 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
<a class="el" href="http://www.keil.com/pack/doc/CMSIS/Pack/html/_config_wizard.html" target="_blank">Configuration Wizard Annotations</a>.
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 for the \ref GlobalMemoryPool. 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 in multiples of \token{4}.
*/

/* ========================================================================================================================== */
/**
\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_<i>device</i>.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. See /ref ObjectMemoryPool.
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. See /ref ObjectMemoryPool.
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. See /ref ObjectMemoryPool.
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. See /ref ObjectMemoryPool.
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. See /ref ObjectMemoryPool.
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. See /ref ObjectMemoryPool.
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. See /ref ObjectMemoryPool.
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}.

*/

/* ========================================================================================================================== */
/**
\page lowPower Configuration for Low-Power Modes

The system thread \b os_IdleThread can be use to switch the system into a low-power mode.  The easiest form to enter a
low-power mode is the execution of the \c __WFE function that puts the processor into a sleep mode where it waits for an
event.

<b>Configuration Example:</b>

\code
#include "RTE_Components.h"
#include CMSIS_device_header            /* Device definitions                 */
 
void os_IdleThread (void) {
  /* The idle demon is a system thread, running when no other thread is       */
  /* ready to run.                                                            */
 
  for (;;) {
    __WFE();                            /* Enter sleep mode                   */
  }
}
\endcode

\note
\c __WFE() is not available at every Cortex-M implementation. Check device manuals for availability.

\section TickLess Tick-less operation

RTX5 provides extension for tick-less operation which is useful for applications that use extensively low-power
modes where the SysTick timer is also disabled. To provide a time-tick in such power-saving modes a wake-up timer is used to
derive timer intervals. The CMSIS-RTOS2 functions \ref osKernelSuspend and \ref osKernelResume control the tick-less operation.

Using this functions allows the RTX5 thread scheduler to stop the periodic kernel tick interrupt. When all active threads
are suspended, the system enters power-down and calculates how long it can stay in this power-down mode. In the power-down
mode the processor and potentially peripherals can be switched off. Only a wake-up timer must remain powered, because this
timer is responsible to wake-up the system after the power-down period expires.

The tick-less operation is controlled from the \b os_IdleThread thread. The wake-up timeout value is set before the system
enters the power-down mode. The function \ref osKernelSuspend calculates the wake-up timeout measured in RTX Timer Ticks; this
value is used to setup the wake-up timer that runs during the power-down mode of the system.

Once the system resumes operation (either by a wake-up time out or other interrupts) the RTX5 thread scheduler is started with
the function \ref osKernelResume. The parameter \a sleep_time specifies the time (in RTX Timer Ticks) that the system was in
power-down mode.

<b>Code Example:</b>
\code
#include "msp.h"                        // Device header

/*----------------------------------------------------------------------------
 *      MSP432 Low-Power Extension Functions
 *---------------------------------------------------------------------------*/
static void MSP432_LP_Entry(void) {
  /* Enable PCM rude mode, which allows to device to enter LPM3 without waiting for peripherals */
  PCM->CTL1 = PCM_CTL1_KEY_VAL | PCM_CTL1_FORCE_LPM_ENTRY;       
  /* Enable all SRAM bank retentions prior to going to LPM3  */
  SYSCTL->SRAM_BANKRET |= SYSCTL_SRAM_BANKRET_BNK7_RET;
  __enable_interrupt();         
  NVIC_EnableIRQ(RTC_C_IRQn);
  /* Do not wake up on exit from ISR */ 
  SCB->SCR |= SCB_SCR_SLEEPONEXIT_Msk;    
  /* Setting the sleep deep bit */
  SCB->SCR |= (SCB_SCR_SLEEPDEEP_Msk);  
}
 
static volatile unsigned int tc;
static volatile unsigned int tc_wakeup;
 
void RTC_C_IRQHandler(void)
{
  if (tc++ > tc_wakeup) 
  {
    SCB->SCR &= ~SCB_SCR_SLEEPONEXIT_Msk;    
    NVIC_DisableIRQ(RTC_C_IRQn);
    NVIC_ClearPendingIRQ(RTC_C_IRQn);
    return;
  }
  if (RTC_C->PS0CTL & RTC_C_PS0CTL_RT0PSIFG)
  {
    RTC_C->CTL0 = RTC_C_KEY_VAL;                 // Unlock RTC key protected registers
    RTC_C->PS0CTL &= ~RTC_C_PS0CTL_RT0PSIFG;
    RTC_C->CTL0 = 0;
    SCB->SCR |= (SCB_SCR_SLEEPDEEP_Msk);
  }
}
 
uint32_t g_enable_sleep = 0;
  
void os_IdleThread (void) {
 
  for (;;) {      
        tc_wakeup = osKernelSuspend();
        /* Is there some time to sleep? */
    if (tc_wakeup > 0) {
      tc = 0;
          /* Enter the low power state */
      MSP432_LP_Entry();
          __wfi();
        } 
    /* Adjust the kernel ticks with the amount of ticks slept */        
        osKernelResume (tc);            
  }
}
\endcode

\note
\c __WFE() is not available at every Cortex-M implementation. Check device manuals for availability.
*/

/*=======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 <a class=el href="http://www.keil.com/pack" target="_blank">Software Pack</a> for the CMSIS-RTOS Validation.
The <b>ARM::CMSIS-RTOS_Validation</b> 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
<a class="el" href="../../RTOS/html/index.html">CMSIS-RTOS API v1</a> that simplifies migration.

Refer to the <a class="el" href="../../RTOS/html/modules.html">Reference</a> 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.

*/