From 96d6da4e252b06dcfdc041e7df23e86161c33007 Mon Sep 17 00:00:00 2001 From: rihab kouki Date: Tue, 28 Jul 2020 11:24:49 +0100 Subject: Official ARM version: v5.6.0 --- .../RTOS2/html/group__CMSIS__RTOS__ThreadMgmt.html | 135 +++++++++++---------- 1 file changed, 71 insertions(+), 64 deletions(-) (limited to 'docs/RTOS2/html/group__CMSIS__RTOS__ThreadMgmt.html') diff --git a/docs/RTOS2/html/group__CMSIS__RTOS__ThreadMgmt.html b/docs/RTOS2/html/group__CMSIS__RTOS__ThreadMgmt.html index dba38af..810da53 100644 --- a/docs/RTOS2/html/group__CMSIS__RTOS__ThreadMgmt.html +++ b/docs/RTOS2/html/group__CMSIS__RTOS__ThreadMgmt.html @@ -340,7 +340,7 @@ Functions
  • 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 BLOCKED, the next READY thread with the highest priority becomes the RUNNING thread.
  • BLOCKED: Threads that are blocked either delayed, waiting for an event to occur or suspended are in the BLOCKED state.
    • -
  • TERMINATED: When osThreadTerminate is called, threads are TERMINATED with resources not yet released.
    • +
  • TERMINATED: When osThreadTerminate is called, threads are TERMINATED with resources not yet released (applies to joinable threads).
  • INACTIVE: Threads that are not created or have been terminated with all resources released are in the INACTIVE state.
    • @@ -368,7 +368,7 @@ Thread State and State Transitions
    int main (void) {
    osKernelInitialize();
    ;
    -
    osThreadNew(thread1, NULL, NULL); // Create thread with default settings
    +
    osThreadNew(thread1, NULL, NULL); // Create thread with default settings
    ;
    osKernelStart();
    }
    @@ -381,12 +381,12 @@ Thread State and State Transitions
    }
    const osThreadAttr_t thread1_attr = {
    -
    .stack_size = 1024 // Create the thread stack with a size of 1024 bytes
    +
    .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
    +
    osThreadNew(thread1, NULL, &thread1_attr); // Create thread with custom sized stack memory
    ;
    }

    Example 3 - Create thread with statically allocated stack

    @@ -442,20 +442,20 @@ Thread State and State Transitions
    }
    const osThreadAttr_t thread1_attr = {
    -
    .priority = osPriorityHigh //Set initial thread priority to high
    +
    .priority = osPriorityHigh //Set initial thread priority to high
    };
    int main (void) {
    ;
    -
    osThreadNew(thread1, NULL, &thread1_attr);
    +
    osThreadNew(thread1, NULL, &thread1_attr);
    ;
    }

    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.

    -
    __NO_RETURN void worker (void *argument) {
    -
    ; // work a lot on data[]
    -
    osDelay(1000);
    -
    osThreadExit();
    +
    __NO_RETURN void worker (void *argument) {
    +
    ; // work a lot on data[]
    +
    osDelay(1000U);
    +
    osThreadExit();
    }
    __NO_RETURN void thread1 (void *argument) {
    @@ -465,11 +465,11 @@ Thread State and State Transitions
    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);
    +
    +
    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]);
    @@ -540,7 +540,8 @@ memory for stack

    Pointer to a memory location for the thread stack (64-bit al stack_size size of stack

    The size (in bytes) of the stack specified by stack_mem.

    -

    Default: 0 as the default is no memory provided with stack_mem.

    +

    Default: 0 as the default is no memory provided with stack_mem.

    +

    /**

    osPriority_t @@ -556,7 +557,8 @@ initial thread priority (default: osPriorityNormal)

    Specifies the initial thr 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. Can safely be set to zero for threads not using secure calls at all. See TrustZone RTOS Context Management.

    -

    Default: token{0} not thread context specified.

    +

    Default: 0 not thread context specified.

    +

    /**

    uint32_t @@ -650,7 +652,7 @@ reserved (must be 0)

    Reserved for future use.

    Enumerator
    osThreadInactive 

    Inactive.

    -

    The thread is created but not actively used, or has been terminated.

    +

    The thread is created but not actively used, or has been terminated (returned for static control block allocation, when memory pools are used osThreadError is returned as the control block is no longer valid)

    osThreadReady 

    Ready.

    @@ -666,11 +668,11 @@ reserved (must be 0)

    Reserved for future use.

    osThreadTerminated 

    Terminated.

    -

    The thread is terminated and all its resources are freed.

    +

    The thread is terminated and all its resources are not yet freed (applies to joinable threads).

    osThreadError 

    Error.

    -

    The thread thread has raised an error condition and cannot be scheduled.

    +

    The thread does not exist (has raised an error condition) and cannot be scheduled.

    osThreadReserved 

    Prevents enum down-size compiler optimization.

    @@ -928,9 +930,9 @@ reserved (must be 0)

    Reserved for future use.

    The function osThreadGetName returns the pointer to the name string of the thread identified by parameter thread_id or NULL in case of an error.

    Note
    This function cannot be called from Interrupt Service Routines.

    Code Example

    -
    void ThreadGetName_example (void) {
    -
    osThreadId_t thread_id = osThreadGetId ();
    -
    const char* name = osThreadGetName (thread_id);
    +
    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
    }
    @@ -955,10 +957,10 @@ reserved (must be 0)

    Reserved for future use.

    The function osThreadGetId returns the thread object ID of the currently running thread or NULL in case of an error.

    Note
    This function may be called from Interrupt Service Routines.

    Code Example

    -
    void ThreadGetId_example (void) {
    -
    osThreadId_t id; // id for the currently running thread
    +
    void ThreadGetId_example (void) {
    +
    osThreadId_t id; // id for the currently running thread
    -
    id = osThreadGetId ();
    +
    id = osThreadGetId();
    if (id == NULL) {
    // Failed to get the id
    }
    @@ -1027,28 +1029,28 @@ reserved (must be 0)

    Reserved for future use.

    • osOK: the priority of the specified thread has been changed successfully.
    • osErrorParameter: thread_id is NULL or invalid or priority is incorrect.
      • -
    • osErrorResource: thread specified by parameter thread_id is in an invalid thread state.
      • +
    • osErrorResource: the thread is in an invalid state.
    • osErrorISR: the function osThreadSetPriority cannot be called from interrupt service routines.
    Note
    This function cannot be called from Interrupt Service Routines.

    Code Example

    #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) {
    +
    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
    }
    -
    :
    +
    :
    }
    @@ -1083,12 +1085,12 @@ reserved (must be 0)

    Reserved for future use.

    Code Example

    #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
    +
    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
    +
    id = osThreadGetId(); // Obtain ID of current running thread
    +
    priority = osThreadGetPriority(id); // Obtain the thread priority
    }
    @@ -1120,12 +1122,12 @@ This function has no impact when called when the kernel is locked, see Code Example

    #include "cmsis_os2.h"
    -
    void Thread_1 (void const *arg) { // Thread function
    -
    osStatus_t status; // status of the executed function
    +
    void Thread_1 (void const *arg) { // Thread function
    +
    osStatus_t status; // status of the executed function
    :
    -
    while (1) {
    -
    status = osThreadYield(); //
    -
    if (status != osOK) {
    +
    while (1) {
    +
    status = osThreadYield();
    +
    if (status != osOK) {
    // an error occurred
    }
    }
    @@ -1159,7 +1161,7 @@ This function has no impact when called when the kernel is locked, see
  • osOK: the thread has been suspended successfully.
  • osErrorParameter: thread_id is NULL or invalid.
    • -
  • osErrorResource: thread specified by parameter thread_id is in an invalid thread state.
    • +
  • osErrorResource: the thread is in an invalid state.
  • osErrorISR: the function osThreadSuspend cannot be called from interrupt service routines.
    • Note
    This function cannot be called from Interrupt Service Routines.
    @@ -1195,7 +1197,7 @@ This function must not be called to suspend the running thread when the k
    • osOK: the thread has been resumed successfully.
    • osErrorParameter: thread_id is NULL or invalid.
      • -
    • osErrorResource: thread specified by parameter thread_id is in an invalid thread state.
      • +
    • osErrorResource: the thread is in an invalid state.
    • osErrorISR: the function osThreadResume cannot be called from interrupt service routines.
    Note
    This function cannot be called from Interrupt Service Routines.
    @@ -1229,7 +1231,7 @@ This function may be called when kernel is locked (NULL or invalid. -
  • osErrorResource: thread specified by parameter thread_id is in an invalid thread state.
    • +
  • osErrorResource: the thread is in an invalid state.
  • osErrorISR: the function osThreadDetach cannot be called from interrupt service routines.
    • Note
    This function cannot be called from Interrupt Service Routines.
    @@ -1261,10 +1263,13 @@ This function may be called when kernel is locked (NULL or invalid. -
  • osErrorResource: parameter thread_id is NULL or refers to a thread that is not an active thread or the thread is not joinable.
    • +
  • osErrorResource: the thread is in an invalid state (ex: not joinable).
  • osErrorISR: the function osThreadJoin cannot be called from interrupt service routines.
    • -
    Note
    This function cannot be called from Interrupt Service Routines.
    +
    Note
    This function cannot be called from Interrupt Service Routines.
    +
    +
    +Only one thread shall call osThreadJoin to join the target thread. If multiple threads try to join simultaneously with the same thread, the results are undefined.
    @@ -1286,7 +1291,7 @@ This function may be called when kernel is locked (
    __NO_RETURN void worker (void *argument) {
    // do something
    -
    osDelay(1000);
    +
    osDelay(1000U);
    osThreadExit();
    }
    @@ -1317,30 +1322,32 @@ This function may be called when kernel is locked (NULL or invalid. -
  • osErrorResource: thread specified by parameter thread_id is in an invalid thread state or no other READY thread exists.
    • +
  • osErrorResource: the thread is in an invalid state or no other READY thread exists.
  • osErrorISR: the function osThreadTerminate cannot be called from interrupt service routines.
    • Note
    This function cannot be called from Interrupt Service Routines.
    -Avoid calling the function with a thread_id that does not exist or has been terminated already.
    +Avoid calling the function with a thread_id that does not exist or has been terminated already. +
    +osThreadTerminate destroys non-joinable threads and removes their thread_id from the system. Subsequent access to the thread_id (for example osThreadGetState) will return an osThreadError. Joinable threads will not be destroyed and return the status osThreadTerminated until they are joined with osThreadJoin.

    Code Example

    #include "cmsis_os2.h"
    -
    void Thread_1 (void *arg); // function prototype for Thread_1
    +
    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
    +
    id = osThreadNew(Thread_1, NULL, NULL); // create the thread
    +
    // do something
    +
    status = osThreadTerminate(id); // stop the thread
    if (status == osOK) {
    -
    // Thread was terminated successfully
    -
    }
    +
    // Thread was terminated successfully
    +
    }
    else {
    -
    // Failed to terminate a thread
    -
    }
    +
    // Failed to terminate a thread
    +
    }
    }
    @@ -1455,7 +1462,7 @@ Avoid calling the function with a thread_id that does not exist or has