From 9f95ff5b6ba01db09552b84a0ab79607060a2666 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Wed, 11 Dec 2019 08:59:21 +0100 Subject: Official ARM version: v5.4.0 Add CMSIS V5.4.0, please refer to index.html available under \docs folder. Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure used in existing projects, and thus avoid projects mass update Note: the following components have been removed from ARM original delivery (as not used in ST packages) - CMSIS_EW2018.pdf - .gitattributes - .gitignore - \Device - \CMSIS - \CoreValidation - \DAP - \Documentation - \DoxyGen - \Driver - \Pack - \RTOS\CMSIS_RTOS_Tutorial.pdf - \RTOS\RTX - \RTOS\Template - \RTOS2\RTX - \Utilities - All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2 Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3 --- docs/RTOS/html/group__CMSIS__RTOS__ThreadMgmt.html | 647 +++++++++++++++++++++ 1 file changed, 647 insertions(+) create mode 100644 docs/RTOS/html/group__CMSIS__RTOS__ThreadMgmt.html (limited to 'docs/RTOS/html/group__CMSIS__RTOS__ThreadMgmt.html') diff --git a/docs/RTOS/html/group__CMSIS__RTOS__ThreadMgmt.html b/docs/RTOS/html/group__CMSIS__RTOS__ThreadMgmt.html new file mode 100644 index 0000000..2f0d2dd --- /dev/null +++ b/docs/RTOS/html/group__CMSIS__RTOS__ThreadMgmt.html @@ -0,0 +1,647 @@ + + + + + +Thread Management +CMSIS-RTOS: Thread Management + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-RTOS +  Version 1.03 +
+
Real-Time Operating System: API and RTX Reference Implementation.
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+Macros | +Enumerations | +Functions
+
+
Thread Management
CMSIS-RTOS API
+
+
+ +

Define, create, and control thread functions. +More...

+ + + + + + + + +

+Macros

#define osThreadDef(name, priority, instances, stacksz)
 Create a Thread Definition with function, priority, and stack requirements. More...
 
#define osThread(name)   &os_thread_def_##name
 Access a Thread definition. More...
 
+ + + + +

+Enumerations

enum  osPriority {
+  osPriorityIdle = -3, +
+  osPriorityLow = -2, +
+  osPriorityBelowNormal = -1, +
+  osPriorityNormal = 0, +
+  osPriorityAboveNormal = +1, +
+  osPriorityHigh = +2, +
+  osPriorityRealtime = +3, +
+  osPriorityError = 0x84 +
+ }
 Priority used for thread control. More...
 
+ + + + + + + + + + + + + + + + + + + +

+Functions

osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument)
 Create a thread and add it to Active Threads and set it to state READY. More...
 
osThreadId osThreadGetId (void)
 Return the thread ID of the current running thread. More...
 
osStatus osThreadTerminate (osThreadId thread_id)
 Terminate execution of a thread and remove it from Active Threads. More...
 
osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority)
 Change priority of an active thread. More...
 
osPriority osThreadGetPriority (osThreadId thread_id)
 Get current priority of an active thread. More...
 
osStatus osThreadYield (void)
 Pass control to next thread that is in state READY. More...
 
+

Description

+

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:

+
    +
  • RUNNING: The thread that is currently running is in the RUNNING state. Only one thread at a time can be in this state.
    • +
  • READY: Threads which are ready to run are in the READY state. Once the RUNNING thread has terminated or is WAITING, the next READY thread with the highest priority becomes the RUNNING thread.
    • +
  • WAITING: Threads that are waiting for an event to occur are in the WAITING state.
    • +
  • INACTIVE: Threads that are not created or terminated are in the INACTIVE state. These threads typically consume no system resources.
    • +
+
+ThreadStatus.png +
+Thread State and State Transitions
+

A CMSIS-RTOS assumes that threads are scheduled as shown in the figure Thread State and State Transitions. The thread states change as follows:

+
    +
  • A thread is created using the function osThreadCreate. This puts the thread into the READY or RUNNING state (depending on the thread priority).
    • +
  • CMSIS-RTOS is pre-emptive. The active thread with the highest priority becomes the RUNNING thread provided it does not wait for any event. The initial priority of a thread is defined with the osThreadDef but may be changed during execution using the function osThreadSetPriority.
    • +
  • The RUNNING thread transfers into the WAITING state when it is waiting for an event.
    • +
  • Active threads can be terminated any time using the function osThreadTerminate. Threads can terminate also by just returning from the thread function. Threads that are terminated are in the INACTIVE state and typically do not consume any dynamic memory resources.
    • +
+

Macro Definition Documentation

+ +
+
+ + + + + + + + +
#define osThread( name)   &os_thread_def_##name
+
+

Access to the thread definition for the function osThreadCreate.

+
Parameters
+ + +
namename of the thread definition object.
+
+
+
Note
CAN BE CHANGED: The parameter to osThread shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
#define osThreadDef( name,
 priority,
 instances,
 stacksz 
)
+
+

Define the attributes of a thread functions that can be created by the function osThreadCreate using osThread. The argument instances defines the number of times that osThreadCreate can be called for the same osThreadDef.

+

Code Example

+
#include "cmsis_os.h"
+
+
void Thread (void const *arg); // function prototype for a Thread
+
osThreadDef (Thread, osPriorityNormal, 3, 0); // define Thread and specify to allow three instances
+
+
void ThreadCreate_example (void) {
+
osThreadId id1, id2, id3;
+
+
id1 = osThreadCreate (osThread (Thread), NULL); // create the thread with id1
+
id2 = osThreadCreate (osThread (Thread), NULL); // create the thread with id2
+
id3 = osThreadCreate (osThread (Thread), NULL); // create the thread with id3
+
if (id1 == NULL) { // handle thread creation for id1
+
// Failed to create the thread with id1
+
}
+
if (id2 == NULL) { // handle thread creation for id2
+
// Failed to create the thread with id2
+
}
+
if (id3 == NULL) { // handle thread creation for id3
+
// Failed to create the thread with id3
+
}
+
:
+
osThreadTerminate (id1); // stop the thread with id1
+
osThreadTerminate (id2); // stop the thread with id2
+
osThreadTerminate (id3); // stop the thread with id3
+
}
+
Parameters
+ + + + + +
namename of the thread function.
priorityinitial priority of the thread function.
instancesnumber of possible thread instances.
stackszstack size (in bytes) requirements for the thread function.
+
+
+
Note
CAN BE CHANGED: The parameters to osThreadDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.
+ +
+
+

Enumeration Type Documentation

+ +
+
+ + + + +
enum osPriority
+
+
Note
MUST REMAIN UNCHANGED: osPriority shall be consistent in every CMSIS-RTOS.
+
+Cannot be called from Interrupt Service Routines.
+

The osPriority 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.

+ + + + + + + + + +
Enumerator
osPriorityIdle  +

priority: idle (lowest)

+
osPriorityLow  +

priority: low

+
osPriorityBelowNormal  +

priority: below normal

+
osPriorityNormal  +

priority: normal (default)

+
osPriorityAboveNormal  +

priority: above normal

+
osPriorityHigh  +

priority: high

+
osPriorityRealtime  +

priority: realtime (highest)

+
osPriorityError  +

system cannot determine priority or thread has illegal priority

+
+ +
+
+

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + +
osThreadId osThreadCreate (const osThreadDef_t * thread_def,
void * argument 
)
+
+
Parameters
+ + + +
[in]thread_defthread definition referenced with osThread.
[in]argumentpointer that is passed to the thread function as start argument.
+
+
+
Returns
thread ID for reference by other functions or NULL in case of error.
+
Note
MUST REMAIN UNCHANGED: osThreadCreate shall be consistent in every CMSIS-RTOS.
+

Start a thread function by adding it to the Active Threads list and set it to state READY. The thread function receives the argument pointer as function argument when the function is started. 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.

+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os.h"
+
+
void Thread_1 (void const *arg); // function prototype for Thread_1
+
osThreadDef (Thread_1, osPriorityNormal, 1, 0); // define Thread_1
+
+
void ThreadCreate_example (void) {
+
osThreadId id;
+
+
id = osThreadCreate (osThread (Thread_1), NULL); // create the thread
+
if (id == NULL) { // handle thread creation
+
// Failed to create a thread
+
}
+
:
+
osThreadTerminate (id); // stop the thread
+
}
+
+
+
+ +
+
+ + + + + + + + +
osThreadId osThreadGetId (void )
+
+
Returns
thread ID for reference by other functions or NULL in case of error.
+
Note
MUST REMAIN UNCHANGED: osThreadGetId shall be consistent in every CMSIS-RTOS.
+

Get the thread ID of the current running thread.

+
Note
Cannot be called from Interrupt Service Routines.
+
+Must not be used inside the idle daemon. This would lead to undefined behavior.
+

Code Example

+
void ThreadGetId_example (void) {
+
osThreadId id; // id for the currently running thread
+
+
id = osThreadGetId ();
+
if (id == NULL) {
+
// Failed to get the id; not in a thread
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
osPriority osThreadGetPriority (osThreadId thread_id)
+
+
Parameters
+ + +
[in]thread_idthread ID obtained by osThreadCreate or osThreadGetId.
+
+
+
Returns
current priority value of the thread function.
+
Note
MUST REMAIN UNCHANGED: osThreadGetPriority shall be consistent in every CMSIS-RTOS.
+

Get the priority of an active thread. In case of a failure the value osPriorityError is returned.

+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os.h"
+
+
void Thread_1 (void const *arg) { // Thread function
+
osThreadId id; // id for the currently running thread
+
osPriority priority; // thread priority
+
+
id = osThreadGetId (); // Obtain ID of current running thread
+
+
if (id != NULL) {
+
priority = osThreadGetPriority (id);
+
}
+
else {
+
// Failed to get the id
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
osStatus osThreadSetPriority (osThreadId thread_id,
osPriority priority 
)
+
+
Parameters
+ + + +
[in]thread_idthread ID obtained by osThreadCreate or osThreadGetId.
[in]prioritynew priority value for the thread function.
+
+
+
Returns
status code that indicates the execution status of the function.
+
Note
MUST REMAIN UNCHANGED: osThreadSetPriority shall be consistent in every CMSIS-RTOS.
+

Change the priority of an active thread.

+

Status and Error Codes
+

+
    +
  • osOK: the priority of the specified thread has been successfully changed.
    • +
  • osErrorParameter: thread_id is incorrect.
    • +
  • osErrorValue: incorrect priority value.
    • +
  • osErrorResource: thread_id refers to a thread that is not an active thread.
    • +
  • osErrorISR: osThreadSetPriority cannot be called from interrupt service routines.
    • +
+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os.h"
+
+
void Thread_1 (void const *arg) { // Thread function
+
osThreadId id; // id for the currently running thread
+
osPriority pr; // thread priority
+
osStatus status; // status of the executed function
+
+
:
+
id = osThreadGetId (); // Obtain ID of current running thread
+
+
if (id != NULL) {
+
status = osThreadSetPriority (id, osPriorityBelowNormal);
+
if (status == osOK) {
+
// Thread priority changed to BelowNormal
+
}
+
else {
+
// Failed to set the priority
+
}
+
}
+
else {
+
// Failed to get the id
+
}
+
:
+
}
+
+
+
+ +
+
+ + + + + + + + +
osStatus osThreadTerminate (osThreadId thread_id)
+
+
Parameters
+ + +
[in]thread_idthread ID obtained by osThreadCreate or osThreadGetId.
+
+
+
Returns
status code that indicates the execution status of the function.
+
Note
MUST REMAIN UNCHANGED: osThreadTerminate shall be consistent in every CMSIS-RTOS.
+

Remove the thread function from the active thread list. If the thread is currently RUNNING the execution will stop.

+
Note
In case that osThreadTerminate terminates the currently running task, the function never returns and other threads that are in the READY state are started.
+

Status and Error Codes
+

+
    +
  • osOK: the specified thread has been successfully terminated.
    • +
  • osErrorParameter: thread_id is incorrect.
    • +
  • osErrorResource: thread_id refers to a thread that is not an active thread.
    • +
  • osErrorISR: osThreadTerminate cannot be called from interrupt service routines.
    • +
+
Note
Cannot be called from Interrupt Service Routines.
+
+Avoid calling the function with a thread_id that does not exist or has been terminated already.
+

Code Example

+
#include "cmsis_os.h"
+
+
void Thread_1 (void const *arg); // function prototype for Thread_1
+
osThreadDef (Thread_1, osPriorityNormal, 1, 0); // define Thread_1
+
+
void ThreadTerminate_example (void) {
+
osStatus status;
+
osThreadId id;
+
+
id = osThreadCreate (osThread (Thread_1), NULL); // create the thread
+
:
+
status = osThreadTerminate (id); // stop the thread
+
if (status == osOK) {
+
// Thread was terminated successfully
+
}
+
else {
+
// Failed to terminate a thread
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
osStatus osThreadYield (void )
+
+
Returns
status code that indicates the execution status of the function.
+
Note
MUST REMAIN UNCHANGED: osThreadYield shall be consistent in every CMSIS-RTOS.
+

Pass control to the next thread that is in state READY. If there is no other thread in the state READY, the current thread continues execution and no thread switching occurs.

+

Status and Error Codes
+

+
    +
  • osOK: the function has been correctly executed.
    • +
  • osErrorISR: osThreadYield cannot be called from interrupt service routines.
    • +
+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os.h"
+
+
void Thread_1 (void const *arg) { // Thread function
+
osStatus status; // status of the executed function
+
:
+
while (1) {
+
status = osThreadYield(); //
+
if (status != osOK) {
+
// thread switch not occurred, not in a thread function
+
}
+
}
+
}
+
+
+
+
+
+ + + + -- cgit