Enhancements to RTOS2 documentation.

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Kernel.txt

@@ -3,7 +3,7 @@
 /** 
 \addtogroup CMSIS_RTOS_KernelCtrl Kernel Information and Control
 \ingroup CMSIS_RTOS
-\brief Provide version/system information and start the RTOS Kernel.
+\brief Provides version/system information and starts/controls the RTOS Kernel.
 \details 
 The kernel Information and Control function group allows to:
   - obtain information about the system and the underlying kernel.
@@ -177,8 +177,9 @@ The function \b osKernelStart starts the RTOS kernel and begins thread switching
 in case of success. Before it is successfully executed, only the functions \ref osKernelGetInfo, \ref osKernelGetState, and
 object creation functions (\b osXxxNew) may be called.
 
+At least one initial thread should be created prior osKernelStart, see \ref osThreadNew.
+
 Possible \ref osStatus_t return values:
-- \em osOK in case of success.
 - \em osError if an unspecific error occurred.
 - \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
  
@@ -211,6 +212,10 @@ The function \b osKernelLock allows to lock all task switches. It returns the pr
 it was locked, \token{0} if it was unlocked), or a negative number representing an error code otherwise (refer to
 \ref osStatus_t).
 
+Possible \ref osStatus_t return values:
+- \em osError if an unspecific error occurred.
+- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
+
 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 
 <b>Code Example</b>
@@ -229,6 +234,10 @@ The function \b osKernelUnlock resumes from \ref osKernelLock. It returns the pr
 it was locked, \token{0} if it was unlocked), or a negative number representing an error code otherwise (refer to
 \ref osStatus_t).
 
+Possible \ref osStatus_t return values:
+- \em osError if an unspecific error occurred.
+- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
+
 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 
 <b>Code Example</b>
@@ -256,6 +265,10 @@ The argument \a lock specifies the lock state as obtained by \ref osKernelLock o
 The function returns the new value of the lock state (\token{1} if it was locked, \token{0} if it was unlocked), or a
 negative number representing an error code otherwise (refer to \ref osStatus_t).
 
+Possible \ref osStatus_t return values:
+- \em osError if an unspecific error occurred.
+- \em osErrorISR if called from an \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routine".
+
 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 
 <b>Code Example</b>
@@ -280,6 +293,10 @@ CMSIS-RTOS provides extension for tick-less operation which is useful for applic
 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 function \b osKernelSuspend suspends the RTX kernel scheduler and thus enables sleep modes.
 
+The return value can be used to determine the amount of system ticks until the next tick-based kernel event will occure, i.e.
+a delayed thread becomed ready again. It is recommended to set up the low power timer to generate a wake-up interrupt based
+on this return value.
+
 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 
 <b>Code Example</b>

CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Thread.txt

@@ -248,17 +248,15 @@ thread with a lower priority.
 /**
 \def osThreadJoinable
 \details
-
-See \ref osThreadJoin.
+A thread in this state can be joined using \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====*/
 /**
 \fn osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr)
@@ -397,8 +395,9 @@ void Thread_1 (void const *arg)  {                         // Thread function
 /**
 \fn osStatus_t osThreadYield (void)
 \details
-The function \b osThreadYield passes control to the next thread that is in the \b READY state. If there is no other thread in
-state \b READY, then the current thread continues execution and no thread switching occurs.
+The function \b osThreadYield passes control to the next thread with the same priority that is in the \b READY state. 
+If there is no other thread with the same priority in state \b READY, then the current thread continues execution and
+no thread switch occurs.
 
 Possible \ref osStatus_t return values:
     - \em osOK: control has been passed to the next thread successfully.
@@ -406,6 +405,7 @@ Possible \ref osStatus_t return values:
     - \em osErrorISR: the function \b osThreadYield cannot be called from interrupt service routines.
 
 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note This function <b>has no impact</b> when called when the kernel is locked, see \ref osKernelLock.
 
 <b>Code Example</b>
 \code
@@ -428,8 +428,8 @@ void Thread_1 (void const *arg)  {                         // Thread function
 \fn osStatus_t osThreadSuspend (osThreadId_t thread_id)
 \details
 The function \b osThreadSuspend suspends the execution of the thread identified by parameter \em thread_id. The thread is put
-into the \em BLOCKED state (\ref osThreadBlocked). The thread is not executed until restarted with the function
-\ref osThreadResume.
+into the \em BLOCKED state (\ref osThreadBlocked). Suspending the running thread will cause a context switch to another
+thread in \em READY state immediately. The suspended thread is not executed until explicitly resumed with the function \ref osThreadResume. 
 
 Threads that are already \em BLOCKED are removed from any wait list and become ready when they are resumed.
 Thus it is not recommended to suspend an already blocked thread.
@@ -441,13 +441,16 @@ Possible \ref osStatus_t return values:
     - \em osErrorISR: the function \b osThreadSuspend cannot be called from interrupt service routines.
 
 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note This function <b>must not</b> be called to suspend the running thread when the kernel is locked, i.e. \ref osKernelLock.
+
 */
 
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 /**
 \fn osStatus_t osThreadResume (osThreadId_t thread_id)
 \details
-The function \b osThreadResume forces a thread identified by parameter \em thread_id which is is \em BLOCKED state to resume operation.
+The function \b osThreadResume puts the thread identified by parameter \em thread_id (which has to be in \em BLOCKED state)
+back to the \em READY state. If the resumed thread has a higher priority than the running thread a context switch occurs immediately.
 
 The thread becomes ready regardless of the reason why the thread was blocked. Thus it is not recommended to resume a thread not suspended
 by \ref osThreadSuspend.
@@ -468,6 +471,9 @@ Possible \ref osStatus_t return values:
     - \em osErrorISR: the function \b osThreadResume cannot be called from interrupt service routines.
 
 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
+\note This function <b>may be</b> called when kernel is locked (\ref osKernelLock). Under this circumstances
+	a potential context switch is delayed until the kernel gets unlocked, i.e. \ref osKernelUnlock or \ref osKernelRestoreLock.
+
 */
 
 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
@@ -614,10 +620,11 @@ The function \b osThreadEnumerate returns the number of enumerated threads or \t
 \details
 The following predefined bit masks can be assigned to set options for a thread object.
 
-Bit Mask                |   Description
-:-----------------------|:-----------------------------------------
-osThreadJoinable        | Thread is created in a join-able state.
-osThreadDetached        | Thread is created in a detached state (default).
+| Bit Mask                | Description                                             |
+| :---------------------- | :------------------------------------------------------ |
+| \ref osThreadDetached   | Create thread in a detached mode (default).             |
+| \ref osThreadJoinable   | Create thread in joinable mode, see \ref osThreadJoin.  |
+
 
 \var osThreadAttr_t::cb_mem
 \details

CMSIS/RTOS2/Include/cmsis_os2.h

@@ -175,8 +175,8 @@ typedef enum {
 #define osFlagsErrorISR       0xFFFFFFFAU ///< osErrorISR (-6).
  
 /// Thread attributes (attr_bits in \ref osThreadAttr_t).
-#define osThreadDetached      0x00000000U ///< Thread created in detached state (default)
-#define osThreadJoinable      0x00000001U ///< Thread created in joinable state
+#define osThreadDetached      0x00000000U ///< Thread created in detached mode (default)
+#define osThreadJoinable      0x00000001U ///< Thread created in joinable mode
  
 /// Mutex attributes (attr_bits in \ref osMutexAttr_t).
 #define osMutexRecursive      0x00000001U ///< Recursive mutex.
@@ -338,7 +338,7 @@ void osKernelResume (uint32_t sleep_ticks);
 uint64_t osKernelGetTickCount (void);
  
 /// Get the RTOS kernel tick frequency.
-/// \return frequency of the kernel tick.
+/// \return frequency of the kernel tick in hertz, i.e. kernel ticks per second.
 uint32_t osKernelGetTickFreq (void);
  
 /// Get the RTOS kernel system timer count.
@@ -346,7 +346,7 @@ uint32_t osKernelGetTickFreq (void);
 uint32_t osKernelGetSysTimerCount (void);
  
 /// Get the RTOS kernel system timer frequency.
-/// \return frequency of the system timer.
+/// \return frequency of the system timer in hertz, i.e. timer ticks per second.
 uint32_t osKernelGetSysTimerFreq (void);