Return values updated.

[cmsis] / CMSIS / DoxyGen / RTOS2 / src / cmsis_os2_Thread.txt

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
//  ==== Thread Management ====
/** 
\addtogroup CMSIS_RTOS_ThreadMgmt Thread Management
\ingroup CMSIS_RTOS CMSIS_RTOSv2
\brief Define, create, and control thread functions.
\details 
The Thread Management function group allows defining, creating, and controlling thread functions in the system.

\note Thread management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

\anchor ThreadStates
Thread states
-------------
Threads can be in the following states:

 - \b RUNNING: The thread that is currently running is in the \ref ThreadStates "RUNNING" state. Only one thread at a time can be in this
   state.
 - \b READY: Threads which are ready to run are in the \ref ThreadStates "READY" state. Once the \ref ThreadStates "RUNNING" thread has terminated, or is
   \ref ThreadStates "BLOCKED", the next \ref ThreadStates "READY" thread with the highest priority becomes the \ref ThreadStates "RUNNING" thread.
 - \b BLOCKED: Threads that are blocked either delayed, waiting for an event to occur or suspended are in the \ref ThreadStates "BLOCKED"
   state.
 - \b TERMINATED: When \ref osThreadTerminate is called, threads are \ref ThreadStates "TERMINATED" with resources not yet released. 
 - \b INACTIVE: Threads that are not created or have been terminated with all resources released are in the \ref ThreadStates "INACTIVE" state.
 
\image html "ThreadStatus.png" "Thread State and State Transitions"


A CMSIS-RTOS assumes that threads are scheduled as shown in the figure <b>Thread State and State Transitions</b>. The thread
states change as follows:
 - A thread is created using the function \ref osThreadNew. This puts the thread into the \ref ThreadStates "READY" or \ref ThreadStates "RUNNING" state
   (depending on the thread priority).
 - CMSIS-RTOS is pre-emptive. The active thread with the highest priority becomes the \ref ThreadStates "RUNNING" thread provided it does not
   wait for any event. The initial priority of a thread is defined with the \ref osThreadAttr_t but may be changed during
   execution using the function \ref osThreadSetPriority.
 - The \ref ThreadStates "RUNNING" thread transfers into the \ref ThreadStates "BLOCKED" state when it is delayed, waiting for an event or suspended.
 - Active threads can be terminated any time using the function \ref osThreadTerminate. Threads can terminate also by just
   returning from the thread function. Threads that are terminated are in the \ref ThreadStates "INACTIVE" state and typically do not consume
   any dynamic memory resources. 

\note 
Refer to \ref threadConfig for RTX5 configuration options.

\anchor thread_examples
Thread Examples
===============
The following examples show various scenarios to create threads:
 
<b>Example 1 - Create a simple thread</b> 

Create a thread out of the function thread1 using all default values for thread attributes and memory from the
\ref GlobalMemoryPool.
 
\code
__NO_RETURN void thread1 (void *argument) {
  // ...
  for (;;) {}
}
 
int main (void) {
  osKernelInitialize();
  ;
  osThreadNew(thread1, NULL, NULL);    // Create thread with default settings
  ;
  osKernelStart(); 
}
\endcode

<b>Example 2 - Create thread with stack non-default stack size</b>
 
Similar to the simple thread all attributes are default. The stack is dynamically allocated from the \ref GlobalMemoryPool
 
\ref osThreadAttr_t.stack_size is used to pass the stack size in Bytes to osThreadNew.

\code
__NO_RETURN void thread1 (void *argument) {
  // ...
  for (;;) {}
}
 
const osThreadAttr_t thread1_attr = {
  .stack_size = 1024                             // Create the thread stack with a size of 1024 bytes
};
 
int main (void) {
  ;  
  osThreadNew(thread1, NULL, &thread1_attr);     // Create thread with custom sized stack memory
  ;
}
\endcode

<b>Example 3 - Create thread with statically allocated stack</b>
 
Similar to the simple thread all attributes are default. The stack is statically allocated using the \c uint64_t array
\c thread1_stk_1. This allocates 64*8 Bytes (=512 Bytes) with an alignment of 8 Bytes (mandatory for Cortex-M stack memory). 
 
\ref osThreadAttr_t.stack_mem holds a pointer to the stacks lowest address. 
 
\ref osThreadAttr_t.stack_size is used to pass the stack size in Bytes to osThreadNew.

\code
__NO_RETURN void thread1 (void *argument) {
  // ...
  for (;;) {}
}
 
static uint64_t thread1_stk_1[64];
 
const osThreadAttr_t thread1_attr = {
  .stack_mem  = &thread1_stk_1[0],
  .stack_size = sizeof(thread1_stk_1)
};
 
int main (void) {
  ;  
  osThreadNew(thread1, NULL, &thread1_attr);    // Create thread with statically allocated stack memory
  ;
}
\endcode

<b>Example 4 - Thread with statically allocated task control block</b>
 
Typically this method is chosen together with a statically allocated stack as shown in Example 2. 
\code 
#include "cmsis_os2.h"
 
//include rtx_os.h for types of RTX objects
#include "rtx_os.h"

__NO_RETURN void thread1 (void *argument) {
  // ...
  for (;;) {}
}
 
static osRtxThread_t thread1_tcb;
 
const osThreadAttr_t thread1_attr = {
  .cb_mem  = &thread1_tcb,
  .cb_size = sizeof(thread1_tcb),
};
 
int main (void) {
  ;
  osThreadNew(thread1, NULL, &thread1_attr);    // Create thread with custom tcb memory
  ;
}
\endcode

<b>Example 5 - Create thread with a different priority</b> 
 
The default priority of RTX is \ref osPriorityNormal. Often you want to run a task with a higher or lower priority. Using the
\ref osThreadAttr_t control structure you can set any initial priority required.

\code
__NO_RETURN void thread1 (void *argument) {
  // ...
  for (;;) {}
}
 
const osThreadAttr_t thread1_attr = {
  .priority = osPriorityHigh            //Set initial thread priority to high   
};
 
int main (void) {
  ;
  osThreadNew(thread1, NULL, &thread1_attr);   
  ;
}
\endcode

<b>Example 6 - Joinable threads</b>
 
In this example a master thread creates four threads with the \ref osThreadJoinable attribute. These will do some work and
return using the \ref osThreadExit call after finished. \ref osThreadJoin is used to synchronize the thread termination. 


\code 
__NO_RETURN void worker (void *argument) {     
    ; // work a lot on data[] 
    osDelay(1000);       
    osThreadExit();
}
 
__NO_RETURN void thread1 (void *argument) {
  osThreadAttr_t worker_attr;
  osThreadId_t worker_ids[4];
  uint8_t data[4][10];

  memset(&worker_attr, 0, sizeof(worker_attr));
  worker_attr.attr_bits = osThreadJoinable;
  
  worker_ids[0] = osThreadNew(worker, &data[0][0], &worker_attr);    
  worker_ids[1] = osThreadNew(worker, &data[1][0], &worker_attr);    
  worker_ids[2] = osThreadNew(worker, &data[2][0], &worker_attr);    
  worker_ids[3] = osThreadNew(worker, &data[3][0], &worker_attr);    
 
  osThreadJoin(worker_ids[0]);
  osThreadJoin(worker_ids[1]);
  osThreadJoin(worker_ids[2]);
  osThreadJoin(worker_ids[3]);
 
  osThreadExit(); 
}
\endcode
   
@{
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\enum osThreadState_t
\details
State of a thread as retrieved by \ref osThreadGetState. In case \b osThreadGetState fails or if it is called from an ISR, it
will return \c osThreadError, otherwise it returns the thread state.

\var osThreadState_t::osThreadInactive
\details The thread is created but not actively used, or has been terminated.

\var osThreadState_t::osThreadReady
\details The thread is ready for execution but not currently running.

\var osThreadState_t::osThreadRunning
\details The thread is currently running.

\var osThreadState_t::osThreadBlocked
\details The thread is currently blocked (delayed, waiting for an event or suspended).

\var osThreadState_t::osThreadTerminated
\details The thread is terminated and all its resources are freed.

\var osThreadState_t::osThreadError
\details The thread thread has raised an error condition and cannot be scheduled.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\enum osPriority_t
\details

The \b osPriority_t value specifies the priority for a thread. The default thread priority should be \a osPriorityNormal.
If an active thread becomes ready that has a higher priority than the currently running thread then a thread switch occurs
immediately. The system continues executing the thread with the higher priority.

To prevent from a priority inversion, a CMSIS-RTOS compliant OS may optionally implement a <b>priority inheritance</b>
method. A priority inversion occurs when a high priority thread is waiting for a resource or event that is controlled by a
thread with a lower priority. Thus causing the high priority thread potentially beeing blocked forever by another thread
with lower priority. To come over this issue the low priority thread controlling the resource should be treated as having
the higher priority until it releases the resource.

\note Priority inheritance only applies to mutexes.

\var osPriority_t::osPriorityIdle
\details This lowest priority should not be used for any other thread. 

\var osPriority_t::osPriorityISR 
\details This highest priority might be used by the RTOS implementation but must not be used for any user thread.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef void (*osThreadFunc_t) (void *argument)
\details Entry function for threads. Setting up a new thread (\ref osThreadNew) will start execution with a call into this
entry function. The optional argument can be used to hand over arbitrary user data to the thread, i.e. to identify the thread
or for runtime parameters.

\param[in] argument Arbitrary user data set on \ref osThreadNew.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\typedef osThreadId_t
\details Returned by:
- \ref osThreadNew
- \ref osThreadGetId
- \ref osThreadEnumerate
- \ref osMutexGetOwner
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\struct osThreadAttr_t
\details
Attributes to configure a thread.

Refer to \ref CMSIS_RTOS_MemoryMgmt for details about usage of
 - osThreadAttr_t::cb_mem
 - osThreadAttr_t::cb_size
 - osThreadAttr_t::stack_mem
 - osThreadAttr_t::stack_size
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\def osThreadJoinable
\details
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)
\details
The function \b osThreadNew starts a thread function by adding it to the list of active threads and sets it to state
\ref ThreadStates "READY". Arguments for the thread function are passed using the parameter pointer \a *argument. When the priority of the
created thread function is higher than the current \ref ThreadStates "RUNNING" thread, the created thread function starts instantly and
becomes the new \ref ThreadStates "RUNNING" thread. Thread attributes are defined with the parameter pointer \a attr. Attributes include
settings for thread priority, stack size, or memory allocation.

The function can be safely called before the RTOS is
started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).

The function \b osThreadNew returns the pointer to the thread object identifier or \token{NULL} in case of an error.

Possible \ref osThreadId_t return values:
- pointer to the thread object, in case of success
- \em NULL, if the priority level is outside the permitted range: \em osPriorityIdle ... \em osPriorityISR.
- \em NULL, if the \em stack_mem is not \em NULL but:
  - \em stack_mem is not a multiple of 8 bytes
  - \em stack_size equals 0
- \em NULL, if \em stack_size is lower smaller than 72 bytes
- \em NULL, if \em stack_size is not zero and not a multiple of 8
- \em NULL, if the control block (attr->cb_mem) is not large enough to hold a thread control block
- \em NULL, if the control block (attr->cb_mem) is not 4 byte aligned  
- \em NULL, if the maximum number of threads have been created already
- \em NULL, if the thread function \em func is \em NULL
- \em 'osErrorISR', if IRQ is masked
- \em 'osErrorISR', in IRQ mode. 

\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

\b Code \b Example

Refer to the \ref thread_examples "Thread Examples" section.
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn const char *osThreadGetName (osThreadId_t thread_id)
\details
The function \b osThreadGetName returns the pointer to the name string of the thread identified by parameter \a thread_id or
\token{NULL} in case of an error.

Possible return values:
- pointer to the name string, in case of success
- \em NULL, if no name has been defined
- \em NULL, if a thread specified by \a thread_id does not exist
- \em NULL, if thread_id is \em NULL.


\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
void ThreadGetName_example (void)  {
  osThreadId_t thread_id = osThreadGetId ();
  const char* name = osThreadGetName (thread_id);
  if (name == NULL) {
    // Failed to get the thread name; not in a thread
  }
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osThreadId_t osThreadGetId (void)
\details
The function \b osThreadGetId returns the thread object ID of the currently running thread or NULL in case of an error.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
void ThreadGetId_example (void)  {
  osThreadId_t id;                                           // id for the currently running thread
   
  id = osThreadGetId ();
  if (id == NULL) {
    // Failed to get the id; not in a thread
  }
}
\endcode
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osThreadState_t osThreadGetState (osThreadId_t thread_id)
\details
The function \b osThreadGetState returns the state of the thread identified by parameter \a thread_id. In case it fails or
if it is called from an ISR, it will return \c osThreadError, otherwise it returns the thread state (refer to
\ref osThreadState_t for the list of thread states).

Possible \ref osThreadState_t return values:
- the state of the thread specified by \a thread_id, in case of success
- \em 'osThreadError', if the thread specified by \a thread_id is \em NULL

- \em 'osThreadError', if if a thread specified by \a thread_id does not exist
- \em 'osThreadError', if IRQ is masked

- \em 'osThreadError', if in IRQ mode.

\note This function \b 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 osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority)
\details
The function \b osThreadSetPriority changes the priority of an active thread specified by the parameter \a thread_id to the
priority specified by the parameter \a priority. 

Possible \ref osStatus_t return values:
- \em 'osOK', if the priority of thread specified by \a thread_id  has been changed successfully
- \em 'osErrorParameter', if the thread specified by \a thread_id is \em NULL
- \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
- \em 'osErrorParameter', if \em osPriorityIdle < \em priority or \em priority > \em osPriorityISR 
- \em 'osErrorResource', if the thread is in state \em 'osThreadInactive' or \em 'osThreadTerminated'
- \em 'osErrorISR', if IRQ is masked
- \em 'osErrorISR', if in IRQ mode.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
#include "cmsis_os2.h"
 
void Thread_1 (void const *arg)  {                          // Thread function
  osThreadId_t id;                                          // id for the currently running thread
  osStatus_t   status;                                      // status of the executed function
   
  :  
  id = osThreadGetId ();                                    // Obtain ID of current running thread
   
  status = osThreadSetPriority (id, osPriorityBelowNormal); // Set thread priority
  if (status == osOK)  {
    // Thread priority changed to BelowNormal
  }
  else {
    // Failed to set the priority
  }
  :  
}
\endcode
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osPriority_t osThreadGetPriority (osThreadId_t thread_id)
\details
The function \b osThreadGetPriority returns the priority of an active thread specified by the parameter \a thread_id.

Possible \ref osPriority_t return values:
- the priority of the thread specified by \em thread_id, in case of success
- \em 'osPriorityError', if the threads specified by \em thread_id is in state \em 'osRtxObjectInactive' or \em 'osRtxObjectTerminated'
- \em 'osPriorityError', if a thread specified by \em thread_id does not exist
- \em 'osPriorityError', if the thread is \em NULL.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

<b>Code Example</b>
\code
#include "cmsis_os2.h"
 
void Thread_1 (void const *arg)  {                         // Thread function
  osThreadId_t id;                                         // id for the currently running thread
  osPriority_t priority;                                   // thread priority
   
  id = osThreadGetId ();                                   // Obtain ID of current running thread
  priority = osThreadGetPriority (id);                     // Obtain the thread priority
}
\endcode
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osThreadYield (void)
\details
The function \b osThreadYield passes control to the next thread with the same priority that is in the \ref ThreadStates "READY" state. 
If there is no other thread with the same priority in state \ref ThreadStates "READY", then the current thread continues execution and
no thread switch occurs. \b osThreadYield does not set the thread to state \ref ThreadStates "BLOCKED". Thus no thread with a lower
priority will be scheduled even if threads in state \ref ThreadStates "READY" are available.

Possible \ref osStatus_t return values:
- \em 'osOK', if control has been passed to the next thread successfully
- \em 'osErrorISR', if IRQ is masked
- \em 'osErrorISR', if in IRQ mode.


\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
#include "cmsis_os2.h"
 
void Thread_1 (void const *arg)  {                         // Thread function
  osStatus_t   status;                                     // status of the executed function
  :
  while (1)  {
    status = osThreadYield();                              // 
    if (status != osOK)  {
      // an error occurred
    }
  }
}
\endcode
*/
/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\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 \ref ThreadStates "BLOCKED" state (\ref osThreadBlocked). Suspending the running thread will cause a context switch to another
thread in \ref ThreadStates "READY" state immediately. The suspended thread is not executed until explicitly resumed with the function \ref osThreadResume. 

Threads that are already \ref ThreadStates "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.

Possible \ref osStatus_t return values:
 - \em 'osOK', if the thread has been suspended successfully
 - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 - \em 'osErrorParameter', if the thread specified by \a thread_id is NULL

 - \em 'osErrorResource', if no thread is in state \em 'osRtxThreadReady' or the kernel is not running

 - \em 'osErrorResource', the the thread specified by \a thread_id is in state \em 'osRtxThreadInactive'

 - \em 'osErrorResource', the the thread specified by \a thread_id is in state \em 'osRtxThreadTerminated'

 - \em 'osErrorISR', if IRQ is masked

 - \em 'osErrorISR', if in IRQ mode.


\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 puts the thread identified by parameter \em thread_id (which has to be in \ref ThreadStates "BLOCKED" state)
back to the \ref ThreadStates "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.

Functions that will put a thread into \ref ThreadStates "BLOCKED" state are:
\ref osEventFlagsWait and \ref osThreadFlagsWait,
\ref osDelay and \ref osDelayUntil,
\ref osMutexAcquire and \ref osSemaphoreAcquire,
\ref osMessageQueueGet,
\ref osMemoryPoolAlloc,
\ref osThreadJoin,
\ref osThreadSuspend.

Possible \ref osStatus_t return values:
 - \em 'osOK', if the thread specified by \a thread_id has been resumed successfully
 - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 - \em 'osErrorParameter', if the thread specified by \a thread_id is \em NULL
 - \em 'osErrorResource', if the state of the thread specified by \a thread_id is not 'Blocked'.
 - \em 'osErrorISR', if IRQ is masked
 - \em 'osErrorISR', in IRQ mode.

\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====*/
/**
\fn osStatus_t osThreadDetach (osThreadId_t thread_id)
\details
The function \b osThreadDetach changes the attribute of a thread (specified by \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 behavior of \ref osThreadDetach on an already detached thread is undefined.

Possible \ref osStatus_t return values:
 - \em 'osOK', if the attribute of the thread specified by \a thread_id has been changed to detached successfully.
 - \em 'osErrorParameter', if \em thread_id is \em NULL
 - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
 - \em 'osErrorResource', if the thread is in state \em 'osRtxThreadInactive'
 - \em 'osErrorResource', if the thread is marked as \em 'osThreadDetached'
 - \em 'osErrorISR', if IRQ is masked
 - \em 'osErrorISR', if in IRQ mode.  


\note This function \b 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 osThreadJoin (osThreadId_t thread_id)
\details
The function \b osThreadJoin waits for the thread specified by \em thread_id to terminate. If that thread has already
terminated, then \ref osThreadJoin returns immediately. The thread must be joinable. By default threads are created with the
attribute \ref osThreadDetached.

Possible \ref osStatus_t return values:
   - \em 'osOK', in case of success
   - \em 'osErrorParameter', if the thread is \em NULL
   - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
   - \em 'osErrorResource', if the thread specified by \a thread_id is marked as not joinable

   - \em 'osErrorResource', if the state of the thread is \em 'osRtxThreadInactive' or \em 'osRtxThreadRunning'
   - \em 'osErrorResource', if the kernel is not running
   - \em 'osErrorISR', if IRQ is masked

   - \em 'osErrorISR', if in IRQ mode.

\note This function \b 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 __NO_RETURN void osThreadExit (void)
\details

The function \b osThreadExit terminates the calling thread. This allows the thread to be synchronized with \ref osThreadJoin.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".

\b Code \b Example
\code
__NO_RETURN void worker (void *argument) {
  // do something
  osDelay(1000);
  osThreadExit();
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn osStatus_t osThreadTerminate (osThreadId_t thread_id)
\details
The function \b osThreadTerminate removes the thread specified by parameter \a thread_id from the list of active threads. If
the thread is currently \ref ThreadStates "RUNNING", the thread terminates and the execution continues with the next \ref ThreadStates "READY" thread. If no
such thread exists, the function will not terminate the running thread, but return \em osErrorResource.

Possible \ref osStatus_t return values:
- \em 'osOK', if the thread specified by \a thread_id has been removed from the active thread list successfully
- \em 'osErrorParameter', if the thread specified by \a thread_id does not exist
- \em 'osErrorParameter', if a thread with \em thread_id is \em NULL
- \em 'osErrorResource', if the thread is in state \em 'osRtxThreadInactive' or \em 'osRtxThreadTerminated'
- \em 'osErrorResource', if no thread is in state \em 'osRtxThreadReady' that can run next
- \em 'osErrorResource', if the kernel is not running
- \em 'osErrorISR', if IRQ is masked

- \em 'osErrorISR', if in IRQ mode.


\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
\note Avoid calling the function with a \em thread_id that does not exist or has been terminated already.

<b>Code Example</b>
\code
#include "cmsis_os2.h"
 
void Thread_1 (void *arg);                             // function prototype for Thread_1
 
void ThreadTerminate_example (void) {
  osStatus_t status;
  osThreadId_t id;
 
  id = osThreadNew (Thread_1, NULL, NULL);             // create the thread
                                                       // do something
  status = osThreadTerminate (id);                     // stop the thread
  if (status == osOK) {
                                                       // Thread was terminated successfully
    }
  else {
                                                       // Failed to terminate a thread
    }
}
\endcode
*/

/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
/**
\fn uint32_t osThreadGetStackSize (osThreadId_t thread_id)
\details
The function \b osThreadGetStackSize returns the stack size of the thread specified by parameter \a thread_id. In case of an
error, it returns \token{0}.
/*
New definition
*/
Possible return values:
- the stack size of the thread
- \em 0, if a thread specified by \a thread_id does not exist
- \em 0, if the thread specified by \em thread_id is \em NULL
- \em 0, if the thread is in state \em 'osRtxObjectInactive'
- \em 0, if IRQ is masked
- \em 0, if in IRQ mode.


\note This function \b 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 uint32_t osThreadGetStackSpace (osThreadId_t thread_id); 
\details
The function \b osThreadGetStackSpace returns the size of unused stack space for the thread specified by parameter
\a thread_id. Stack watermark recording during execution needs to be enabled (refer to \ref threadConfig). In case of an
error, it returns \token{0}.

Possible return values:
- the size of unused stack space, in case of success
- \em 0, if a thread specified by \a thread_id does not exist
- \em 0, if the thread with \em thread_id is \em NULL
- \em 0, if the thread is in state \em 'osRtxObjectInactive'
- \em 0, if stack watermark is not enabled
- \em 0, if IRQ is masked
- \em 0, if in IRQ mode


\note This function \b 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 uint32_t osThreadGetCount (void)
\details
The function \b osThreadGetCount returns the number of active threads or \token{0} in case of an error.

\note This function \b 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 uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items)
\details
The function \b osThreadEnumerate returns the number of enumerated threads or \token{0} in case of an error.

Possible return values:
- number of enumerated threads, in case of success
- \em 0, if \em thread_array is \em NULL
- \em 0, if \em array_items = 0
- \em 0, if IRQ is masked
- \em 0, if in IRQ mode.

\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
*/

/// @}


// these struct members must stay outside the group to avoid double entries in documentation
/**
\var osThreadAttr_t::attr_bits
\details
The following predefined bit masks can be assigned to set options for a thread object.

| 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
Pointer to a memory location for the thread control block object. This can optionally be used for custom memory management systems.\n
Default: \token{NULL} (uses kernel memory management).

\var osThreadAttr_t::cb_size
\details
The size of the memory block passed with \ref cb_mem. Must be the size of a thread control block object or larger.

\var osThreadAttr_t::name
\details
Pointer to a string with a human readable name of the thread object.\n
Default: \token{NULL}.

\var osThreadAttr_t::priority
\details
Specifies the initial thread priority with a value from #osPriority_t.\n
Default: \token{osPriorityNormal}

\var osThreadAttr_t::reserved
\details
Reserved for future use (set to '0').\n
Default: \token{0}.

\var osThreadAttr_t::stack_mem
\details
Pointer to a memory location for the thread stack, \b must be 64-bit aligned. This can optionally be used for custom memory
management systems.\n
Default: \token{NULL} (uses kernel memory management).

\var osThreadAttr_t::tz_module
\details
TrustZone Thread Context Management Identifier to allocate context memory for threads. The RTOS kernel that runs in
non-secure state calls the interface functions defined by the header file TZ_context.h. Can safely be set to zero
for threads not using secure calls at all. 
See <a href="../../Core/html/group__context__trustzone__functions.html">TrustZone RTOS Context Management</a>.

\var osThreadAttr_t::stack_size
\details
The size of the stack specified by \ref stack_mem in Bytes.
*/