|
|
@@ -1,75 +1,5 @@
|
|
|
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
|
|
|
/**
|
|
|
-\mainpage
|
|
|
-
|
|
|
-The <b>CMSIS-RTOS v2 (CMSIS-RTOS2)</b> provides generic RTOS interfaces for Arm® Cortex® processor-based
|
|
|
-devices. It provides a standardized API for software components that require RTOS functionality and gives therefore serious
|
|
|
-benefits to the users and the software industry:
|
|
|
- - CMSIS-RTOS2 provides basic features that are required in many applications.
|
|
|
- - The unified feature set of the CMSIS-RTOS2 reduces learning efforts and simplifies sharing of software components.
|
|
|
- - Middleware components that use the CMSIS-RTOS2 are RTOS agnostic and are easier to adapt.
|
|
|
- - Standard project templates of the CMSIS-RTOS2 may be shipped with freely available CMSIS-RTOS2 implementations.
|
|
|
-
|
|
|
-\note The CMSIS-RTOS API Version 2 defines a minimum feature set. Implementations with extended features may be provided by
|
|
|
- the RTOS vendors.
|
|
|
-
|
|
|
-The CMSIS-RTOS2 manages the resources of the microcontroller system and implements the concept of parallel threads that run
|
|
|
-concurrently.
|
|
|
-
|
|
|
-Applications frequently require several concurrent activities. CMSIS-RTOS2 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-RTOS2 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 a user application.
|
|
|
-
|
|
|
-The CMSIS-RTOS2 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-RTOS2 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 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-RTOS2 has the following fundamental modifications:
|
|
|
- - The functions osXxxxNew replace osXxxxCreate functions; osXxxxNew and osXxxxDelete create and destroy objects.
|
|
|
- - The C function \c main is no longer started as a thread (this was an optional feature in CMSIS-RTOS v1).
|
|
|
- - Functions that return osEvent have been replaced.
|
|
|
-
|
|
|
-CMSIS-RTOS2 provides an translation layer to <a class="el" href="../../RTOS/html/index.html">CMSIS-RTOS v1</a>. It
|
|
|
-is possible to intermix \ref rtos_api2 and <a class="el" href="../../RTOS/html/functionOverview.html">CMSIS-RTOS C API v1</a>
|
|
|
-within the same application. Over time, you may migrate to the new API as explained in \ref os2Migration.
|
|
|
-
|
|
|
-CMSIS-RTOS2 is not POSIX compliant, but has provisions to enable a C++11/C++14 interface.
|
|
|
-
|
|
|
-The following sections provide further details about CMSIS-RTOS2 and the RTX reference implementation.
|
|
|
- - \subpage rtos_revisionHistory documents changes made in each version for CMSIS-RTOS v2 and RTX v5.
|
|
|
- - \subpage genRTOS2IF provides an overview about the APIs available with CMSIS-RTOS v2.
|
|
|
- - \subpage functionOverview lists the CMSIS-RTOS2 API functions and the header file %cmsis_os2.h.
|
|
|
- - \subpage rtosValidation describes the validation suite that is publicly available.
|
|
|
- - \subpage os2Migration shows how to use CMSIS-RTOS2 in existing projects and lists function differences to CMSIS-RTOS v1.
|
|
|
- - \subpage rtx5_impl provides general information about the operation and usage of RTX v5.
|
|
|
-
|
|
|
-<hr>
|
|
|
-
|
|
|
-CMSIS-RTOS2 in ARM::CMSIS Pack
|
|
|
-------------------------------
|
|
|
-\anchor directory
|
|
|
-
|
|
|
-The following files relevant to CMSIS-RTOS2 are present in the <b>ARM::CMSIS</b> Pack directories:
|
|
|
-Directory | Content
|
|
|
-:----------------------------|:-----------------------------------------------------------------------
|
|
|
-\b CMSIS/Documentation/RTOS2 | This documentation
|
|
|
-\b CMSIS/RTOS2/Include | \ref cmsis_os2_h
|
|
|
-\b CMSIS/RTOS2/RTX | CMSIS-RTOS2 reference implementation based on RTX version 5
|
|
|
-\b CMSIS/RTOS2/Source | Generic <b>OS tick</b> implementations for various processors based on \ref rtos_os_tick_api
|
|
|
-\b CMSIS/RTOS2/Template | Compatibility layer to <a class="el" href="../../RTOS/html/index.html">CMSIS-RTOS v1</a>
|
|
|
-*/
|
|
|
-
|
|
|
-
|
|
|
-/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
|
|
|
-/**
|
|
|
\page rtos_revisionHistory Revision History
|
|
|
|
|
|
\section GenRTOS2Rev CMSIS-RTOS API Version 2
|
|
|
@@ -411,26 +341,35 @@ The default implementations provided along with CMSIS are
|
|
|
For devices not implementing GIC, PTIM nor GTIM please refer to the according device family pack and select the
|
|
|
proper implementations.
|
|
|
|
|
|
-\section cre_UsingIRQs Using IRQ Interrupts
|
|
|
-
|
|
|
-The Keil RTX5 kernel uses the following interrupts:
|
|
|
-- Timer interrupt (SysTick or alternative peripheral timer) to generate periodic timer ticks
|
|
|
-- SVC (Supervisor Call) when calling the majority of RTX functions from \b Thread mode
|
|
|
-- PendSV (request for system-level service) when calling certain RTX functions from \b Handler mode
|
|
|
-
|
|
|
-Interrupts can be used without limitation. Interrupt priority grouping can be used with some restrictions:
|
|
|
-- IRQ interrupts are never disabled by RTX Kernel for Arm Cortex-M3/M4/M7/M23/M33 cores.
|
|
|
-- Software interrupt 0 is used by RTX and cannot be used in an application.
|
|
|
-- RTX uses its own SVC Handler which is automatically linked from the library.
|
|
|
-- When interrupt \b priority \b grouping is used, the PRIGROUP must be set before the \ref osKernelStart() function is
|
|
|
- called. The kernel reads the value of PRIGROUP to correctly set internal interrupt pre-emption priorities.
|
|
|
-- Allowed values for \b PRIGROUP are from 0 to 6. The PRIGROUP value 7 will cause RTX to fail.
|
|
|
-- The lowest two pre-emption priorities are reserved for RTX kernel, all remaining pre-emption priorities are available to
|
|
|
- be used in an application.
|
|
|
+\section cre_UsingIRQs Using Interrupts on Cortex-M
|
|
|
+
|
|
|
+On Cortex-M processors, the RTX5 kernel uses the following interrupt exceptions. The table below also lists the
|
|
|
+priorities that must be assigned to these interrupts.
|
|
|
+
|
|
|
+Handler | Priority | Interrupt/Exception
|
|
|
+:-------|:---------|:----------------------------
|
|
|
+SysTick | lowest | Kernel system timer interrupt to generate periodic timer ticks
|
|
|
+PendSV | lowest | PendSV (request for system-level service) when calling certain RTX functions from \b Handler mode
|
|
|
+SCV | lowest+1 | Supervisor Call used to enter the RTOS kernel from \b Thread mode
|
|
|
+
|
|
|
+Other device interrupts can be used without limitation. For Arm Cortex-M3/M4/M7/M23/M33 processors, interrupts are never disabled by RTX Kernel.
|
|
|
+
|
|
|
+<b>Usage of interrupt priority grouping</b>
|
|
|
+- The interrupt priority grouping should be configured using the CMSIS-Core function NVIC_SetPriorityGrouping before calling the function
|
|
|
+ \ref osKernelStart(). The RTX kernel uses the priority group value to setup the priority for SysTick and PendSV interrupts.
|
|
|
+- The RTX kernel sets the priority for the interrupts/exceptions listed in above table and uses the lowest two priority levels.
|
|
|
- Do not change the priority used by the RTX kernel. If this cannot be avoided, ensure that the preempt priority of
|
|
|
SysTick/PendSV is lower than SVC.
|
|
|
-- Check the <b>main stack size</b> configured from the device startup file if you see sporadic crashes of your application.
|
|
|
- Supervisor Calls (SVCs) are used when calling RTX functions from Thread mode. All SVC calls use the main stack.
|
|
|
+- Permitted priority group values are 0 to 6. The priority group value 7 will cause RTX to fail as there is only one priority level available.
|
|
|
+- The <b>main stack</b> is used to run the RTX functionality. It is therefore required to configure sufficient stack for the RTX kernel execution.
|
|
|
+
|
|
|
+<b>Code Example</b>
|
|
|
+\code
|
|
|
+osKernelInitialize(); // initialize RTX
|
|
|
+NVIC_SetPriorityGrouping (3); // setup priority grouping
|
|
|
+tread_id = osThreadNew(tread_func, NULL, NULL); // create some threads
|
|
|
+osKernelStart (); // start RTX kernel
|
|
|
+\endcode
|
|
|
|
|
|
\section cre_rtx_proj_specifics Add support for RTX specific functions
|
|
|
If you require some of the \ref rtx5_specific "RTX specific functions" in your application code, \#include the
|
|
|
@@ -445,7 +384,7 @@ If you require some of the \ref rtx5_specific "RTX specific functions" in your a
|
|
|
|
|
|
Once the target application generates event information, it can be viewed in the µVision debugger using the \b Event
|
|
|
\b Recorder.
|
|
|
- */
|
|
|
+*/
|
|
|
|
|
|
|
|
|
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
|
|
|
@@ -468,18 +407,17 @@ Your application's \c main() should implement at least the following in the give
|
|
|
-# Initialize the CMSIS-RTOS kernel using \ref osKernelInitialize.
|
|
|
-# Optionally, create a new thread \c app_main, which is used as a main thread using \ref osThreadNew. Alternatively, threads
|
|
|
can be created in \c main() directly.
|
|
|
--# Start the RTOS scheduler using \ref osKernelStart. This function does not return in case of successful execution. Any
|
|
|
- application code after \b osKernelStart will not be executed unless \b osKernelStart fails.
|
|
|
+-# Start the RTOS scheduler using \ref osKernelStart which also configure system tick timer and RTOS specific interrupts.
|
|
|
+ This function does not return in case of successful execution. Any application code after \b osKernelStart will therefore not be executed.
|
|
|
|
|
|
-\note Interrupts (like SVC for example) used by the kernel are initialized in \ref osKernelInitialize. In case priorities and
|
|
|
+\note Interrupts are initialized in \ref osKernelStart. Modifying basic In case priorities and
|
|
|
groupings in the NVIC are altered by the application after the above sequence it might be necessary to call
|
|
|
-\ref osKernelInitialize again. You might observe weird misbehaviour possibly catched by \ref osRtxErrorNotify or causing a hard fault.
|
|
|
-
|
|
|
-\note The tick timer is configured during \ref osKernelStart. The tick interval is calculated based on the \c SystemCoreClock variable.
|
|
|
+\ref osKernelInitialize again. Incorrect ossibly catched by \ref osRtxErrorNotify or causing a hard fault.
|
|
|
|
|
|
+\note The tick timer is configured during \ref osKernelStart.
|
|
|
\section Scheduler
|
|
|
|
|
|
-RTX5 implements a low-latency preemtive scheduler. Major parts of RTX5 are executed in handler mode such as
|
|
|
+RTX5 implements a low-latency preemptive scheduler. Major parts of RTX5 are executed in handler mode such as
|
|
|
- \ref SysTick_Handler used for time-based scheduling.
|
|
|
- \ref SVC_Handler used for lock-based scheduling.
|
|
|
- \ref PendSV_Handler used for interrupt-based scheduling.
|
|
|
@@ -496,13 +434,13 @@ four threads (1, 2, 3, and 4). Threads 1 and 2 share the same priority, thread 3
|
|
|
a time-slice basis (round-robin). The time-slice for round-robin scheduling can be configured, see Round-Robin Timeout in \ref systemConfig.
|
|
|
|
|
|
Thread 2 unblocks thread 3 by an arbitrary RTOS-call (executed in SVC handler mode) at time index 2. The scheduler switches to
|
|
|
-thread 3 immidiately because thread 3 has the highest priority. Thread 4 is still blocked.
|
|
|
+thread 3 immediately because thread 3 has the highest priority. Thread 4 is still blocked.
|
|
|
|
|
|
At time index 4 an interrupt (ISR) occurs and preempts the SysTick_Handler. RTX does not add any latency to the interrupt
|
|
|
service execution. The ISR routine uses an RTOS-call that unblocks thread 4. Instead of switching to thread 4 immediately
|
|
|
the PendSV flag is set to defer the context switching. The PendSV_Handler is executed right after the SysTick_Handler returns
|
|
|
-and the defered context switch to thread 4 is carried out. As soon as highest priority thread 4 blocks again by using
|
|
|
-a blocking RTOS-call execution is switched back to thread 3 immidiately during time index 5.
|
|
|
+and the deferred context switch to thread 4 is carried out. As soon as highest priority thread 4 blocks again by using
|
|
|
+a blocking RTOS-call execution is switched back to thread 3 immediately during time index 5.
|
|
|
|
|
|
At time index 5 thread 3 uses a blocking RTOS-call as well. Thus the scheduler switches back to thread 2 for time index 6.
|
|
|
At time index 7 the scheduler uses the round-robin mechanism to switch to thread 1 and so on.
|
|
|
@@ -857,11 +795,11 @@ using the CMSIS-RTOS RTX kernel. The configuration options are explained in deta
|
|
|
- \ref msgQueueConfig provides several parameters to configure the \ref CMSIS_RTOS_Message functions.
|
|
|
|
|
|
The file "RTX_Config.c" contains default implementations of the functions \ref osRtxIdleThread and \ref osRtxErrorNotify. Both functions
|
|
|
-can simply be overwritten with a custimized behavior by redefining them as part of the user code.
|
|
|
+can simply be overwritten with a customized behavior by redefining them as part of the user code.
|
|
|
|
|
|
The configuration file uses <b>Configuration Wizard Annotations</b>. Refer to <b>Pack - Configuration Wizard Annotations</b> for details.
|
|
|
Depending on the development tool, the annotations might lead to a more user-friendly graphical representation of the
|
|
|
-settings. The screenshot below is a screenshot from the µVision \b Configuration \b Wizard view:
|
|
|
+settings. The picture below shows the µVision \b Configuration \b Wizard view in MDK:
|
|
|
|
|
|
\image html config_wizard.png "RTX_Config.h in Configuration Wizard View"
|
|
|
|
|
|
@@ -1286,6 +1224,8 @@ The interface files to the processor hardware are:
|
|
|
- <b>%rtx_core_cm.h</b> defines processor specific helper functions and the interfaces to Core Registers and Core Peripherals.
|
|
|
- <b>%os_tick.h</b> is the \ref CMSIS_RTOS_TickAPI that defines the interface functions to the SysTick timer.
|
|
|
|
|
|
+\note
|
|
|
+ - The CMSIS-Core variable \c SystemCoreClock is used to configure the SysTick timer.
|
|
|
|
|
|
\subsection tpCortexM3_M4_M7_M33 Cortex-M3/M4/M7/M33 target processor
|
|
|
|
|
|
@@ -1307,8 +1247,10 @@ The interface files to the processor hardware are:
|
|
|
- <b>%rtx_core_cm.h</b> defines processor specific helper functions and the interfaces to Core Registers and Core Peripherals.
|
|
|
- <b>%os_tick.h</b> is the \ref CMSIS_RTOS_TickAPI that defines the interface functions to the SysTick timer.
|
|
|
|
|
|
-\subsection tpCortexA5_A7_A9 Cortex-A5/A7/A9 target processor
|
|
|
+\note
|
|
|
+ - The CMSIS-Core variable \c SystemCoreClock is used to configure the SysTick timer.
|
|
|
|
|
|
+\subsection tpCortexA5_A7_A9 Cortex-A5/A7/A9 target processor
|
|
|
|
|
|
|
|
|
|
Reinhard Keil