![]() |
CMSIS-RTOS2
Version 2.0.0
Real-Time Operating System: API and RTX Reference Implementation
|
Define, create, and control thread functions. More...
Data Structures | |
struct | osThreadAttr_t |
Attributes structure for thread. More... | |
Macros | |
#define | osThreadJoinable 0x00000001U |
Thread created in joinable state. More... | |
#define | osThreadDetached 0x00000000U |
Thread attributes (attr_bits in osThreadAttr_t). More... | |
Typedefs | |
typedef void(* | os_thread_func_t )(void *argument) |
Entry point of a thread. More... | |
typedef void * | osThreadId_t |
Functions | |
osThreadId_t | osThreadNew (os_thread_func_t func, void *argument, const osThreadAttr_t *attr) |
Create a thread and add it to Active Threads. More... | |
const char * | osThreadGetName (osThreadId_t thread_id) |
Get name of a thread. More... | |
osThreadId_t | osThreadGetId (void) |
Return the thread ID of the current running thread. More... | |
osThreadState_t | osThreadGetState (osThreadId_t thread_id) |
Get current thread state of a thread. More... | |
osStatus_t | osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority) |
Change priority of a thread. More... | |
osPriority_t | osThreadGetPriority (osThreadId_t thread_id) |
Get current priority of a thread. More... | |
osStatus_t | osThreadYield (void) |
Pass control to next thread that is in state READY. More... | |
osStatus_t | osThreadSuspend (osThreadId_t thread_id) |
Suspend execution of a thread. More... | |
osStatus_t | osThreadResume (osThreadId_t thread_id) |
Resume execution of a thread. More... | |
osStatus_t | osThreadDetach (osThreadId_t thread_id) |
Detach a thread (thread storage can be reclaimed when thread terminates). More... | |
osStatus_t | osThreadJoin (osThreadId_t thread_id) |
Wait for specified thread to terminate. More... | |
__NO_RETURN void | osThreadExit (void) |
Terminate execution of current running thread. More... | |
osStatus_t | osThreadTerminate (osThreadId_t thread_id) |
Terminate execution of a thread. More... | |
uint32_t | osThreadGetStackSize (osThreadId_t thread_id) |
Get stack size of a thread. More... | |
uint32_t | osThreadGetStackSpace (osThreadId_t thread_id) |
Get available stack space of a thread based on stack watermark recording during execution. More... | |
uint32_t | osThreadGetCount (void) |
Get number of active threads. More... | |
uint32_t | osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items) |
Enumerate active threads. More... | |
The Thread Management function group allows defining, creating, and controlling thread functions in the system. The function main is a special thread function that is started at system initialization and has the initial priority osPriorityNormal.
Threads can be in the following states:
A CMSIS-RTOS assumes that threads are scheduled as shown in the figure Thread State and State Transitions. The thread states change as follows:
The following examples show various scenarios to create threads:
Example 1 - Create a simple thread
Create a thread out of the function thread1 using all default values for thread attributes and memory from the Global Memory Pool.
Example 2 - Create thread with stack non-default stack size
Similar to the simple thread all attributes are default. The stack is dynamically allocated from the Global Memory Pool
osThreadAttr_t::stack_size is used to pass the stack size in Bytes to osThreadNew.
Example 3 - Create thread with statically allocated stack
Similar to the simple thread all attributes are default. The stack is statically allocated using the uint64_t array thread1_stk_1. This allocates 64*8 Bytes (=512 Bytes) with an alignment of 8 Bytes (mandatory for Cortex-M stack memory).
osThreadAttr_t::stack_mem holds a pointer to the stacks lowest address.
osThreadAttr_t::stack_size is used to pass the stack size in Bytes to osThreadNew.
Example 4 - Thread with statically allocated task control block
Typically this method is chosen together with a statically allocated stack as shown in Example 2. os_objectSize macros supply the size of OS objects. RTX5 has the following internal definitions to determine the size of OS objects:
Include "rtx_os.h" to access these macros.
Example 5 - Create thread with a different priority
The default priority of RTX is osPriorityNormal. Often you want to run a task with a higher or lower priority. Using the osThreadAttr_t control structure you can set any inital priority required.
Example 6 - Joinable threads
In this example a master thread creates four threads with the osThreadJoinable attribute. These will do some work and return using the osThreadExit call after finished. osThreadJoin is used to synchronize the thread termination.
struct osThreadAttr_t |
Data Fields | ||||||||
---|---|---|---|---|---|---|---|---|
const char * | name |
name of the thread String with a human readable name of the thread object. | ||||||
uint32_t | attr_bits |
attribute bits The following predefined bit masks can be assigned to set options for a thread object.
| ||||||
void * | cb_mem |
memory for control block Pointer to a memory location for the thread object. This can optionally be used for custom memory management systems. Specify NULL to use the kernel memory management. | ||||||
uint32_t | cb_size |
size of provided memory for control block The size of the memory block passed with cb_mem. Must be the size of a thread control block object or larger. | ||||||
void * | stack_mem |
memory for stack Pointer to a memory location for the thread stack. This can optionally be used for custom memory management systems. Specify NULL to use the kernel memory management. | ||||||
uint32_t | stack_size |
size of stack The size of the stack specified by stack_mem in Bytes. | ||||||
osPriority_t | priority |
initial thread priority (default: osPriorityNormal) Specifies the initial thread priority with a value from osPriority_t. | ||||||
TZ_ModuleId_t | tz_module |
TrustZone module identifier. 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. See TrustZone RTOS Context Management. | ||||||
uint32_t | reserved |
reserved (must be 0) Reserved for future use. Must be 0. |
#define osThreadJoinable 0x00000001U |
See osThreadJoin.
#define osThreadDetached 0x00000000U |
Thread created in detached state (default)
A thread in this state cannot be joined using osThreadJoin.
void(* os_thread_func_t)(void *argument) |
Thread ID identifies the thread.
enum osThreadState_t |
enum osPriority_t |
The osPriority_t value specifies the priority for a thread. The default thread priority should be osPriorityNormal. If a Thread is active that has a higher priority than the currently executing thread, then a thread switch occurs immediately to execute the new task.
To prevent from a priority inversion, a CMSIS-RTOS compliant OS may optionally implement a priority inheritance 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.
osThreadId_t osThreadNew | ( | os_thread_func_t | func, |
void * | argument, | ||
const osThreadAttr_t * | attr | ||
) |
[in] | func | thread function. |
[in] | argument | pointer that is passed to the thread function as start argument. |
[in] | attr | thread attributes; NULL: default values. |
Start a thread function by adding it to the Active Threads list and set it to state READY. Arguments for the thread function are passed using the parameter pointer *argument. When the priority of the created thread function is higher than the current RUNNING thread, the created thread function starts instantly and becomes the new RUNNING thread. Thread attributes are defined with the parameter pointer attr. Attributes include settings for thread priority, stack size, or memory allocation.
const char * osThreadGetName | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
osThreadId_t osThreadGetId | ( | void | ) |
Get the thread ID of the current running thread.
Code Example:
osThreadState_t osThreadGetState | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
Return the state of the thread identified by parameter thread_id. See osThreadState_t for possible states.
osStatus_t osThreadSetPriority | ( | osThreadId_t | thread_id, |
osPriority_t | priority | ||
) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
[in] | priority | new priority value for the thread function. |
Change the priority of an active thread.
osStatus_t return values:
Code Example:
osPriority_t osThreadGetPriority | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
Get the priority of an active thread. In case of failure, the value osPriorityError is returned.
Code Example:
osStatus_t osThreadYield | ( | void | ) |
Pass control to the next thread that is in state READY. If there is no other thread in state READY, then the current thread continues execution and no thread switching occurs.
Code Example:
osStatus_t osThreadSuspend | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
Suspends execution of the thread identified by parameter thread_id. Thread is put into the state Blocked (osThreadBlocked). The thread is not executed until restarted with the function osThreadResume.
osStatus_t osThreadResume | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
Forces a thread in BLOCKED state, specified with thread_id, to resume operation. Functions that will put a thread into BLOCKED state are: osEventFlagsWait and osThreadFlagsWait, osDelay and osDelayUntil, osMutexAcquire and osSemaphoreAcquire, osMessageQueueGet, osThreadJoin, osThreadSuspend.
osStatus_t osThreadDetach | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
Changes the attribute of a thread specified in thread_id to osThreadDetached. Detached threads are not joinable with osThreadJoin. When a detached thread is terminated all resources are returned to the system. The behaviour of osThreadDetach on an already detached thread is undefined.
osStatus_t osThreadJoin | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
Waits for the thread specified by thread_id to terminate. If that thread has already terminated, then osThreadJoin returns immediately. The thread referred to by thread_id must joinable. By default threads are created with the attribute osThreadJoinable. The thread may not have been detached by osThreadDetach.
__NO_RETURN void osThreadExit | ( | void | ) |
osThreadExit terminates the calling thread. This allows the thread to be synchronized with osThreadJoin.
osStatus_t osThreadTerminate | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
Remove the thread function from the active thread list. If the thread is currently /b RUNNING the execution stops and the thread terminates.
*uint32_t osThreadGetStackSize | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
uint32_t osThreadGetStackSpace | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | thread ID obtained by osThreadNew or osThreadGetId. |
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.
uint32_t osThreadGetCount | ( | void | ) |
osThreadEnumerate | ( | osThreadId_t * | thread_array, |
uint32_t | array_items | ||
) |
[out] | thread_array | pointer to array for retrieving thread IDs. |
[in] | array_items | maximum number of items in array for retrieving thread IDs. |