RTOS2 Documentation Updates

CMSIS/DoxyGen/RTOS2/src/cmsis_os2.txt

@@ -422,7 +422,7 @@ When pool does not provide sufficient memory the creation of the object fails an
 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 Example:
+<b> Code Example: </b> 
 \code{.c}
 /*----------------------------------------------------------------------------
  * CMSIS-RTOS 'main' function template
@@ -436,7 +436,7 @@ The following example shows how to create an OS object using static memory.
 #include "rtx_os.h"
  
 //The thread function instanced in this example
-void *worker(void *arg)
+void worker(void *arg)
 {
   while(1) 
   {
@@ -472,7 +472,7 @@ osThreadId_t th1;
 /*----------------------------------------------------------------------------
  * Application main thread
  *---------------------------------------------------------------------------*/
-void *app_main (void *argument) {
+void app_main (void *argument) {
 	uint32_t param = NULL;
 	
 	//Create an instance of the worker thread with static resources (TCB and stack)
@@ -679,9 +679,6 @@ Data Storage Memory size [bytes]       | \c OS_MEMPOOL_DATA_SIZE  | Defines the
 */
 
 
-
-
-
 /* ========================================================================================================================== */
 /**
 \page msgQueueConfig Message Queue Configuration
@@ -697,31 +694,115 @@ Data Storage Memory size [bytes]       | \c OS_MSGQUEUE_DATA_SIZE | Defines the
 
 */
 
+/* ========================================================================================================================== */
+/**
+\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====*/
 /**

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Kernel.txt

@@ -17,7 +17,7 @@ initial priority \a osPriorityNormal.
 
 When reaching \b main, it is necessary to:
 -# Call osKernelInitialize() to initialize the CMSIS-RTOS Kernel
--# Setup device peripherals and create other RTOS objects using the \b os*Create functions.
+-# Setup device peripherals and create other RTOS objects using the \b os*New functions.
 -# Start the Kernel and begin thread switching by calling osKernelStart().
 
 <b>Code Example</b>
@@ -28,7 +28,7 @@ int main (void) {
   // initialize peripherals here
  
   // create 'thread' functions that start executing,
-  // example: tid_name = osThreadCreate (osThread(name), NULL);
+  // example: tid_name = osThreadNew(thread, NULL, NULL);
  
   osKernelStart ();                         // start thread execution 
 }
@@ -55,15 +55,30 @@ State of the Kernel. Can be retrieved by \ref osKernelGetState.
 /**
 \fn osStatus_t osKernelInitialize (void)
 \details
+ 
+\return Returns \ref osStatus_t with \ref osOK in case of success. 
+\return Returns \ref osError if an internal error prevents the kernel initialization.
+ 
+Initialize the RTOS Kernel. Before osKernelInitialize is successfully executed no RTOS function may be called.
+ 
+The RTOS kernel does not start thread switching until the function osKernelStart is called.
+ 
+<b> Code Example:</b>
+\code{.c}
+int main (void) {
+  osKernelInitialize ();                    // initialize CMSIS-RTOS at first
+  ;                                         // ...   
+}
+\endcode
 
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
 \fn osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
 \details
-Retrieve API and kernel version of the underlying RTOS kernel and a human readable identifier string of the kernel.
-
-\b Example
+Retrieve API and kernel version of the underlying RTOS kernel and a human readable identifier string for the kernel.
+ 
+<b>Code Example:</b>
 \code{.c}
 void info (void) {
   char infobuf[100];
@@ -83,20 +98,59 @@ void info (void) {
 /**
 \fn osKernelState_t osKernelGetState (void)
 \details
+\return The state of the kernel is represented in the \ref osKernelState_t enum. \ref osKernelGetState can be safely called before the RTOS is initialized.
+
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osKernelGetState from an ISR will return \ref osKernelError. 
+ 
+<b>Code Example:</b>
+\code{.c}
+int main (void) {
+  // System Initialization
+  SystemCoreClockUpdate();
+  // ...
+  if(osKernelGetState() == osKernelInactive) {     // Is the kernel initialized?
+     osKernelInitialize();                          // Initialize CMSIS-RTOS kernel		 
+  }
+  ;
+}
+\endcode
 
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
 \fn osStatus_t osKernelStart (void)
 \details
+Start the RTOS Kernel and begin thread switching.
+The function osKernelStart will not return to its calling function in case of success.
+
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines". Calling \ref osKernelStart from an ISR will return \ref osErrorISR.
+ 
+<b>Code Example:</b>
+\code{.c}
+int main (void) {
+  // System Initialization
+  SystemCoreClockUpdate();
+  // ...
+	if(osKernelGetState() == osKernelInactive) { 
+    osKernelInitialize();                        	 
+	}
+   ; // ... Start Threads
+  if (osKernelGetState() == osKernelReady) {        // If kernel is ready to run...
+    osKernelStart();                                // ... start thread execution
+  }
 
+  while(1);                                         // only reached in case of error
+}
+\endcode
 */
+
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
 \fn uint32_t osKernelLock (void)
 \details
 Allows to lock all task switches. 
-\b Example
+<b>Code Example:</b>
 \code{.c}
 uint32_t lock;
 
@@ -120,7 +174,7 @@ Resumes from \ref osKernelLock.
 \details
 CMSIS-RTOS 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 functions osKernelSuspend and osKernelResume control the tick-less operation.
 
-\b Example
+<b>Code Example:</b>
 \code{.c}
 void os_idle_demon (void) {
   /* The idle demon is a system thread, running when no other thread is       */

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Message.txt

@@ -66,7 +66,7 @@ Attributes structure for message queue.
 /** 
 \fn osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);
 \details
-\b Example:
+<b>Code Example:</b>
 \code{.c}
 
 #include "cmsis_os2.h"                                           // CMSIS RTOS header file
@@ -131,8 +131,6 @@ void *Thread_MsgQueue2 (void *argument) {
 }
 \endcode
 
-\todo Example formatting does not use syntax highlighting and links to known identifiers
-
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /** 

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Sema.txt

@@ -108,7 +108,7 @@ osSemaphoreId_t semaphore;                         // Semaphore ID
 //
 //   Thread 1 - High Priority - Active every 3ms
 //
-void *thread1 (void *argument) {
+void thread1 (void *argument) {
   int32_t value;
 
   while (1) {
@@ -126,7 +126,7 @@ void *thread1 (void *argument) {
 //   Thread 2 - Normal Priority - looks for a free semaphore and uses
 //                                the resource whenever it is available
 //
-void *thread2 (void *argument) {
+void thread2 (void *argument) {
   while (1) {
     osSemaphoreAcquire (semaphore, osWaitForever);  // Wait indefinitely for a free semaphore
                                                  // OK, the interface is free now, use it.
@@ -163,7 +163,6 @@ The \a millisec timeout can have the following values:
 
 The return value indicates the number of available tokens (the semaphore count value). If 0 is returned, then no semaphore was available.
 
-\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
@@ -195,5 +194,8 @@ used. The Semaphore may be created again using the function \ref osSemaphoreNew.
  - \em osErrorISR: \ref osSemaphoreDelete cannot be called from interrupt service routines.
  - \em osErrorResource: the semaphore object could not be deleted.
  - \em osErrorParameter: the parameter \a semaphore_id is incorrect.
-*/
+
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osSemaphoreDelete from an ISR will return \ref osErrorISR.
+ */
 /// @}

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Thread.txt

@@ -252,11 +252,16 @@ Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 \def osThreadJoinable
 \details
 
+See \ref osThreadJoin.
+
+
 */
 /**
 \def osThreadDetached
 \details
 
+A thread in this state cannot be joined using \ref osThreadJoin.
+
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
@@ -290,7 +295,7 @@ Get the thread ID of the current running thread.
 \note
 Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 
-\b Example:
+<b>Code Example:</b>
 \code{.c}
 void ThreadGetId_example (void)  {
   osThreadId id;                                           // id for the currently running thread
@@ -309,6 +314,10 @@ void ThreadGetId_example (void)  {
 
 Return the state of the thread identified by parameter \em thread_id.
 See \ref osThreadState_t for possible states.
+ 
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadGetState from an ISR will return \ref osThreadError.
+
 
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
@@ -324,10 +333,11 @@ Change the priority of an active thread.
     - \em osErrorResource: parameter \em thread_id refers to a thread that is not an active thread.
     - \em osErrorISR: the function \b osThreadSetPriority cannot be called from interrupt service routines.
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 
-\b Example:
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadSetPriority from an ISR will return \ref osErrorISR. 
+
+<b>Code Example:</b>
 \code{.c}
 #include "cmsis_os2.h"
  
@@ -361,10 +371,10 @@ void Thread_1 (void const *arg)  {                         // Thread function
 
 Get the priority of an active thread. In case of failure, the value \b osPriorityError is returned.
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadGetPriority from an ISR will return \ref osErrorISR. 
 
-\b Example:
+<b>Code Example:</b>
 \code{.c}
 #include "cmsis_os2.h"
  
@@ -391,10 +401,10 @@ void Thread_1 (void const *arg)  {                         // Thread function
 Pass control to the next thread that is in state \b READY. If there is no other thread in state \b READY, 
 then the current thread continues execution and no thread switching occurs.
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadYield from an ISR will return \ref osErrorISR. 
 
-\b Example:
+<b>Code Example:</b>
 \code{.c}
 #include "cmsis_os2.h"
  
@@ -417,6 +427,10 @@ void Thread_1 (void const *arg)  {                         // Thread function
 Suspends execution of the thread identified by parameter \em thread_id. Thread is put into the state \em Blocked (\ref osThreadBlocked).
 The thread is not executed until restarted with the function \ref osThreadResume.
 
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadSuspend from an ISR will return \ref osErrorISR. 
+
+
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
@@ -431,6 +445,10 @@ Functions that will put a thread into BLOCKED state are:
 \ref osThreadJoin,
 \ref osThreadSuspend.
 
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadResume from an ISR will return \ref osErrorISR. 
+
+
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
@@ -439,8 +457,8 @@ Functions that will put a thread into BLOCKED state are:
 Changes the attribute of a thread specified in \em thread_id to \ref osThreadDetached. Detached threads are not joinable with \ref osThreadJoin. 
 When a detached thread is terminated all resources are returned to the system. The behaviour of \ref osThreadDetach on an already detached thread is undefined.
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadDetach from an ISR will return \ref osErrorISR. 
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
@@ -450,10 +468,10 @@ Waits for the thread specified by \em thread_id to terminate.
 If that thread has already terminated, then \ref osThreadJoin returns immediately.  
 The thread referred to by thread_id must joinable. By default threads are created with the attribute \ref osThreadJoinable. The thread may not have been detached by \ref osThreadDetach.
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadJoin from an ISR will return \ref osErrorISR. 
 
-\todo See Example 5
+\todo See Example 6
 
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
@@ -463,18 +481,15 @@ Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 
 osThreadExit terminates the calling thread. This allows the thread to be synchronized with osThreadJoin. 
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
 \fn osStatus_t osThreadTerminate (osThreadId_t thread_id)
 \details
-Remove the thread function from the active thread list. If the thread is currently /b RUNNING the execution stops and the thread
-terminates.
+Remove the thread function from the active thread list. If the thread is currently /b RUNNING the execution stops and the thread terminates.
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadTerminate from an ISR will return \ref osErrorISR. 
 
 \code
 #include "cmsis_os2.h"
@@ -507,8 +522,8 @@ void ThreadTerminate_example (void) {
 osThreadGetStackSpace returns the size of unused stack space for the thread passed in thread_id.
 If this function is not implemented or stack checking is disabled it will return 0.
 
-\note
-Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osThreadGetStackSpace from an ISR will return 0. 
 */
 
 /// @}

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_ThreadFlags.txt

@@ -32,13 +32,13 @@ static void EX_Signal_1 (void)  {
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /** \fn osStatus osThreadFlagsClear (int32_t flags)
 \details
-Clear the event flags of a thread flags object. 
+Clear the specified event flags set for the a calling thread. 
 
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /** \fn int32_t osThreadFlagsGet (void)
 \details
-Return the event flags currently set in a thread flags object. 
+Return the event flags currently set for the calling thread. 
  
 */
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
@@ -63,7 +63,7 @@ When these thread flags are already set, the function returns instantly. Otherwi
 :
 void *Thread (void* arg) {
 :
-  osThreadFlagsGet (0x00000001ul, NULL, osWaitForever); //Wait forever until event 0x01 is set.
+  osThreadFlagsWait (0x00000001ul, NULL, osWaitForever); //Wait forever until event 0x01 is set.
 :
 }
 \endcode

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Timer.txt

@@ -122,6 +122,7 @@ Start or restart the timer.
  - \em osErrorParameter: \a timer_id is incorrect.
 
 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osTimerStart from an ISR will return \ref osErrorISR. 
  
 <b>Code Example</b>
 \code{.c}
@@ -166,6 +167,7 @@ Stop the timer.
  - \em osErrorResource: the timer is not started.
 
 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osTimerStop from an ISR will return \ref osErrorISR. 
 
 <b>Code Example</b>
 \code{.c}
@@ -213,6 +215,7 @@ Delete the timer object.
  - \em osErrorParameter: \a timer_id is incorrect.
 
 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+Calling \ref osTimerDelete from an ISR will return \ref osErrorISR. 
 
 <b>Code Example</b>
 \code{.c}