first iteration of feedback
diff --git a/CMSIS/DoxyGen/RTOS2/rtos.dxy b/CMSIS/DoxyGen/RTOS2/rtos.dxy
index c4607ae..2fc74c6 100644
--- a/CMSIS/DoxyGen/RTOS2/rtos.dxy
+++ b/CMSIS/DoxyGen/RTOS2/rtos.dxy
@@ -755,12 +755,12 @@
./src/cmsis_os2.txt \
./src/cmsis_os2_Kernel.txt \
./src/cmsis_os2_Thread.txt \
- ./src/cmsis_os2_Wait.txt \
./src/cmsis_os2_ThreadFlags.txt \
./src/cmsis_os2_Event.txt \
+ ./src/cmsis_os2_Wait.txt \
+ ./src/cmsis_os2_Timer.txt \
./src/cmsis_os2_Mutex.txt \
./src/cmsis_os2_Sema.txt \
- ./src/cmsis_os2_Timer.txt \
./src/cmsis_os2_MemPool.txt \
./src/cmsis_os2_Message.txt \
./src/cmsis_os2_Status.txt \
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os.txt
index 4e1b507..3ce4c46 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os.txt
@@ -183,21 +183,25 @@
\section CMSIS_RTOS_ISR_Calls Calls from Interrupt Service Routines
-\todo Can any of the new functions be called from ISRs?
+The following CMSIS-RTOS2 functions can be called from threads and Interrupt Service Routines (ISR):
+\todo what about - \ref osKernelGetState
+ - \ref osThreadFlagsSet, \ref osThreadFlagsClear, \ref osThreadFlagsGet
+ - \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
-The following CMSIS-RTOS functions can be called from threads and Interrupt Service Routines (ISR):
+
+In addition, the following legacy CMSIS-RTOS1 functions can be called from threads and Interrupt Service Routines (ISR):
+\todo verify
- \ref osKernelRunning
- - \ref osSemaphoreRelease
- - \ref osMemoryPoolAlloc, \ref osMemoryPoolFree
- - \ref osMessageQueuePut, \ref osMessageQueueGet
- \ref osMailQueueAlloc, \ref osMailQueueGet, \ref osMailQueuePut, \ref osMailQueueFree
+
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.
-Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISRs at the same time.
-If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code \b osErrorISRRecursive.
*/
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2.txt
index 745ae1e..96848fe 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2.txt
@@ -1,4 +1,4 @@
-/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
+/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\mainpage
@@ -169,30 +169,46 @@
\section CMSIS_RTOS_TimeOutValue Timeout Value
-The timeout value specifies the number of timer ticks until a timeout or time delay elapses. The value is an upper bound and
+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.
+\todo R: should we introduce a define osWaitNone which would translate to 0.
+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.
-For a value of \b 1 the system waits until the next timer tick occurs. That means that the actual timeout value can be one
-timer tick less than the specified timeout value.
+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
-\todo Can any of the new functions be called from ISRs?
+The following CMSIS-RTOS2 functions can be called from threads and Interrupt Service Routines (ISR):
+\todo R: what about - \ref osKernelGetState
-The following CMSIS-RTOS functions can be called from threads and Interrupt Service Routines (ISR):
- - \ref osKernelRunning
- - \ref osSemaphoreRelease
- - \ref osMemoryPoolAlloc, \ref osMemoryPoolFree
- - \ref osMessageQueuePut, \ref osMessageQueueGet
+ - \ref osThreadFlagsSet, \ref osThreadFlagsClear, \ref osThreadFlagsGet
+ - \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
+
+In addition, the following legacy CMSIS-RTOS1 functions can be called from threads and Interrupt Service Routines (ISR):
+\todo R: verify
+\todo B: make references to RTOS1 functions
+
+ - osKernelRunning
+ - osMailQueueAlloc, osMailQueueGet, osMailQueuePut, osMailQueueFree
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.
-Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISRs at the same time.
-If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code \b osErrorISRRecursive.
*/
@@ -336,7 +352,7 @@
\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 is mentioned where applicable.
+and the configuration options are mentioned where applicable.
\section KernelTimer RTX Kernel Timer Tick and Thread Management
@@ -347,8 +363,7 @@
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 switch itself is implemented in the HAL_CMx.x hardware abstraction layer source files. The
-thread context contains all CPU registers (R0 - R12), the return address (LR), the program counter (PC), and the processor
+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.
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Event.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Event.txt
index e7ede44..4d7b213 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Event.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Event.txt
@@ -108,7 +108,7 @@
\fn int32_t osEventFlagsWait (osEventFlagsId_t ef_id, int32_t flags, uint32_t options, uint32_t millisec)
\details
Suspend the execution of the current \b RUNNING thread until any or all specified event flags with the parameter \a flags are set.
-The /em options parameter specifies the wait condition.
+The \em options parameter specifies the wait condition.
|Option | |
|--------------------|-------------------------------------------------------|
@@ -116,7 +116,7 @@
|\b osFlagsWaitAll | Wait for all flags. |
|\b osFlagsAutoClear | Clear flags which have been specified to wait for. |
-If osFlagsAutoClear is not set in the options /ref osEventFlagsClear can be used to clear flags manually.
+If osFlagsAutoClear is not set in the options \ref osEventFlagsClear can be used to clear flags manually.
When these event flags are already set, the function returns instantly. Otherwise the thread is put into the state \b WAITING.
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Mutex.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Mutex.txt
index f2fc325..7e79cb9 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Mutex.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Mutex.txt
@@ -114,7 +114,7 @@
- when \a millisec is set to \b osWaitForever the function will wait for an infinite time until the mutex becomes available.
- all other values specify a time in millisecond for a timeout.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osOK: the mutex has been obtained.
- \em osErrorTimeoutResource: the mutex could not be obtained in the given time.
- \em osErrorResource: the mutex could not be obtained when no timeout was specified.
@@ -147,7 +147,7 @@
\details
Release a Mutex that was obtained with \ref osMutexAcquire. Other threads that currently wait for the same mutex will be now put into the state \b READY.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osOK: the mutex has been correctly released.
- \em osErrorResource: the mutex was not obtained before.
- \em osErrorParameter: the parameter \a mutex_id is incorrect.
@@ -186,7 +186,7 @@
Delete a Mutex object. The function releases internal memory obtained for Mutex handling. After this call the \a mutex_id is no longer valid and cannot be
used. The Mutex may be created again using the function \ref osMutexNew.
-<b>\ref CMSIS_RTOS_Status</b>
+\ref osStatus_t return values:
- \em osOK: the mutex object has been deleted.
- \em osErrorISR: \ref osMutexDelete cannot be called from interrupt service routines.
- \em osErrorResource: all tokens have already been released.
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Sema.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Sema.txt
index ce3043d..2a78fae 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Sema.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Sema.txt
@@ -174,7 +174,7 @@
\details
Release a Semaphore token. This increments the count of available semaphore tokens.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osOK: the semaphore has been released.
- \em osErrorResource: all tokens have already been released.
- \em osErrorParameter: the parameter \a semaphore_id is incorrect.
@@ -183,7 +183,7 @@
/**
\fn uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id)
\details
-Returns the count of available semaphores of the semaphore object specified by /em semaphore_id.
+Returns the count of available semaphores of the semaphore object specified by \em semaphore_id.
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
@@ -193,7 +193,7 @@
Delete a Semaphore object. The function releases internal memory obtained for Semaphore handling. After this call the \a semaphore_id is no longer valid and cannot be
used. The Semaphore may be created again using the function \ref osSemaphoreNew.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osOK: the semaphore object has been deleted.
- \em osErrorISR: \ref osSemaphoreDelete cannot be called from interrupt service routines.
- \em osErrorResource: the semaphore object could not be deleted.
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Status.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Status.txt
index 2285593..51d584a 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Status.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Status.txt
@@ -1,18 +1,55 @@
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
-// ==== Status and Error Codes ====
+// ==== Definitions ====
/**
-\addtogroup CMSIS_RTOS_Status Status and Error Codes
+\addtogroup CMSIS_RTOS_Definitions Definitions
\ingroup CMSIS_RTOS
-\brief Status and Error Codes returned by CMSIS-RTOS API functions.
-\details The Status and Error Codes section lists all the return values that the CMSIS-RTOS functions will return.
+\brief Constants and enumerations used by many CMSIS-RTOS functions.
+\details The following constants and enumerations are used by many CMSIS-RTOS function calls.
@{
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef osStatus_t
\details
-The \b osStatus_t enumeration defines the event status and error codes that are returned by the CMSIS-RTOS functions.
+The \b osStatus_t enumeration defines the event status and error codes that are returned by many CMSIS-RTOS functions.
*/
+
+/**
+\def osWaitForever
+\details A special \ref CMSIS_RTOS_TimeOutValue that informs the RTOS to wait infinite until a resource becomes available.
+It applies to the following functions:
+ - \ref osThreadFlagsWait : \copybrief osThreadFlagsWait
+ - \ref osEventFlagsWait : \copybrief osEventFlagsWait
+ - \ref osMutexAcquire : \copybrief osMutexAcquire
+ - \ref osSemaphoreAcquire : \copybrief osSemaphoreAcquire
+ - \ref osMemoryPoolAlloc : \copybrief osMemoryPoolAlloc
+ - \ref osMessageQueuePut : \copybrief osMessageQueuePut
+ - \ref osMessageQueueGet : \copybrief osMessageQueueGet
+*/
+
+/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
+/** \def osFlagsWaitAny
+
+\todo
+Reference:
+ - \ref osEventFlagsWait
+ - \ref osThreadFlagsWait
+*/
+/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
+/** \def osFlagsWaitAll
+
+Reference:
+ - \ref osEventFlagsWait
+ - \ref osThreadFlagsWait
+*/
+/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
+/** \def osFlagsAutoClear
+
+Reference:
+ - \ref osEventFlagsWait
+ - \ref osThreadFlagsWait
+*/
+
/// @}
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Thread.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Thread.txt
index d7f1ef3..67da0a8 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Thread.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Thread.txt
@@ -151,7 +151,7 @@
Change the priority of an active thread.
-\ref CMSIS_RTOS_Status
+\ref osStatus_t return values:
- \em osOK: the priority of the specified thread has been changed successfully.
- \em osErrorParameter: the value of the parameter \em thread_id or parameter \em priority is incorrect.
- \em osErrorResource: parameter \em thread_id refers to a thread that is not an active thread.
@@ -428,7 +428,7 @@
Pointer to a memory location for the thread stack. This can optionally be used for custom memory management systems.
Specify \token{NULL} to use the kernel memory management.
-\var osThreadAttr_t::stack_mem
+\var osThreadAttr_t::stack_size
\details
The size of the stack specified by \ref stack_mem in Bytes.
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_ThreadFlags.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_ThreadFlags.txt
index de7e8b8..d17fee4 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_ThreadFlags.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_ThreadFlags.txt
@@ -12,27 +12,6 @@
@{
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
-/** \def osFlagsWaitAny
-
-Reference:
- - \ref osEventFlagsWait
- - \ref osThreadFlagsWait
-*/
-/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
-/** \def osFlagsWaitAll
-
-Reference:
- - \ref osEventFlagsWait
- - \ref osThreadFlagsWait
-*/
-/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
-/** \def osFlagsAutoClear
-
-Reference:
- - \ref osEventFlagsWait
- - \ref osThreadFlagsWait
-*/
-/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/** \fn int32_t osThreadFlagsSet (osThreadId_t thread_id, int32_t flags )
Set the thread flags for a thread instance specified by \em thread_id. This function may be used also within interrupt service routines.
The threads waiting for the flag set will be notified to resume from WAITING state.
@@ -64,7 +43,7 @@
/** \fn int32_t osThreadFlagsWait (int32_t flags, uint32_t options, uint32_t millisec);
Suspend the execution of the current \b RUNNING thread until any or all specified thread flags with the parameter \a flags are set.
-The /em options parameter specifies the wait condition.
+The \em options parameter specifies the wait condition.
|Option | |
|--------------------|-------------------------------------------------------|
@@ -72,7 +51,7 @@
|\b osFlagsWaitAll | Wait for all flags. |
|\b osFlagsAutoClear | Clear flags which have been specified to wait for. |
-If osFlagsAutoClear is not set in the options /ref osThreadFlagClear can be used to clear flags manually.
+If osFlagsAutoClear is not set in the options \ref osThreadFlagsClear can be used to clear flags manually.
When these thread flags are already set, the function returns instantly. Otherwise the thread is put into the state \b WAITING.
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Timer.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Timer.txt
index 9232183..d140457 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Timer.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Timer.txt
@@ -117,7 +117,7 @@
\details
Start or restart the timer.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osOK: the specified timer has been started or restarted.
- \em osErrorISR: \ref osTimerStart cannot be called from interrupt service routines.
- \em osErrorParameter: \a timer_id is incorrect.
@@ -160,7 +160,7 @@
\details
Stop the timer.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osOK: the specified timer has been stopped.
- \em osErrorISR: \ref osTimerStop cannot be called from interrupt service routines.
- \em osErrorParameter: \a timer_id is incorrect.
@@ -208,7 +208,7 @@
\details
Delete the timer object.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osOK: the specified timer has been deleted.
- \em osErrorISR: \ref osTimerDelete cannot be called from interrupt service routines.
- \em osErrorParameter: \a timer_id is incorrect.
diff --git a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Wait.txt b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Wait.txt
index 0d52743..4082773 100644
--- a/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Wait.txt
+++ b/CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Wait.txt
@@ -10,15 +10,7 @@
@{
*/
-/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
-/**
-\def osWaitForever
-\details
-Reference:
- - \ref osDelay
- - \ref osDelayUntil
-*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osDelay (uint32_t millisec);
@@ -31,7 +23,7 @@
For a value of <b>1</b>, the system waits until the next timer tick occurs. That means that the actual time delay may be up
to one timer tick less.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osEventTimeout: the time delay is executed.
- \em osErrorISR: \ref osDelay cannot be called from interrupt service routines.
@@ -64,7 +56,7 @@
\ref osKernelGetTime can be used to retrieve the current elapsed time of the kernel in millisec.
-<b>\ref CMSIS_RTOS_Status</b>\n
+\ref osStatus_t return values:
- \em osEventTimeout: the time delay is executed.
- \em osErrorISR: \ref osDelayUntil cannot be called from interrupt service routines.