RTOS2: updated API - limited osThreadFlagsClear/Get to current running thread and...

[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 POSIX translation layer and a C++ interface.
\todo Investigate into a flexible C++ interface and potential POSIX translation

<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 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.

<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. 

*/

/*=======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" is used to define the configuration parameters of CMSIS-RTOS RTX. This file 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 that is used, this might lead to a more user friendly graphical representation of the settings. The following is a screenshot of the same configuration file using µVision's Configuration Wizard view:

\image html config_wizard.png "RTX_Conf_CM.c in Configuration Wizard View"

The configuration options are explained on these pages:
- \subpage threadConfig

*/


/* ========================================================================================================================== */
/**
\page threadConfig Thread Configuration

The CMSIS-RTOS RTX provides several parameters for the thread configuration.

\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 to 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.

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|
|-------------------------------------------------------------------|-----------------|-----------|
|Number of concurrent running user threads                          |\c OS_THREAD_NUM    |Indicates the maximum number of threads that will run at the same time (including main).|
|Default Thread stack size [bytes]                                  |\c OS_STACK_SIZE    |Specifies the default stack size (in words) for threads that are defined with osThreadDef \a stacksz = 0.|
|Number of threads with user-provided stack size                    |\c OS_THREAD_USER_STACK_NUM    |Indicates the number of threads that are created with \ref osThreadNew \a stack_size specifies the stack size requirement of that thread.|
|stackCheck                                            |\c OS_STACK_CHECK   |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.|
|stackUsage                                              |\c OS_STACK_WATERMARK    |Initializes the thread stack with a watermark pattern that can be used to determine the maximum stack usage within each thread.|
|processorMode                                |\c OS_PRIVILEGE_MODE    |Controls the processor mode (privileged/unprivileged)|
*/

/*=======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.

*/