Source: Mculover666

1. CMSIS-RTOS API

The CMSIS-RTOS API is a set of general interface protocols established by ARM for RTOS kernels. It provides a set of “standard API interfaces” that can be ported to various RTOS, allowing upper-layer software, middleware, libraries, and other components to work normally across different RTOS.

This API is represented by two files: cmsis-os.h and cmsis-os.c, which means that different RTOS kernels adapt the interfaces in the .c file using their own set of implementations, while users only need to call the APIs provided in the .h file to write applications.

This article will list the APIs and macro definitions provided by CMSIS-RTOS, along with demo usage for each type of API. Learners only need to understand these concepts and be able to comprehend applications written using the CMSIS-RTOS API.

In TencentOS-tiny, it is as follows.

• Implementation of CMSIS-RTOS API v1.02 based on TencentOS-tiny:
• cmsis_os.h
• cmsis_os.c
• Implementation of CMSIS-RTOS API v2.1.3 based on TencentOS-tiny:
• cmsis_os2.h
• cmsis_os2.c

The overall architecture of the CMSIS-RTOS API is shown in the figure below:

2. CMSIS-RTOS API List

Below is a list of all APIs provided by CMSIS-RTOS version v1.02.

Error codes used by all APIs in CMSIS-RTOS (cmsis-os.h):

typedef enum {
    osOK                    =     0,       ///< function completed; no error or event occurred.
    osEventSignal           =  0x08,       ///< function completed; signal event occurred.
    osEventMessage          =  0x10,       ///< function completed; message event occurred.
    osEventMail             =  0x20,       ///< function completed; mail event occurred.
    osEventTimeout          =  0x40,       ///< function completed; timeout occurred.
    osErrorParameter        =  0x80,       ///< parameter error: a mandatory parameter was missing or specified an incorrect object.
    osErrorResource         =  0x81,       ///< resource not available: a specified resource was not available.
    osErrorTimeoutResource  =  0xC1,       ///< resource not available within given time: a specified resource was not available within the timeout period.
    osErrorISR              =  0x82,       ///< not allowed in ISR context: the function cannot be called from interrupt service routines.
    osErrorISRRecursive     =  0x83,       ///< function called multiple times from ISR with same object.
    osErrorPriority         =  0x84,       ///< system cannot determine priority or thread has illegal priority.
    osErrorNoMemory         =  0x85,       ///< system is out of memory: it was impossible to allocate or reserve memory for the operation.
    osErrorValue            =  0x86,       ///< value of a parameter is out of range.
    osErrorOS               =  0xFF,       ///< unspecified RTOS error: run-time error but no other error message fits.
    os_status_reserved      =  0x7FFFFFFF  ///< prevent from enum down-size compiler optimization.
} osStatus;

Some optional controls for the CMSIS-RTOS API (cmsis-os.h):

#define osFeature_MainThread   1       ///< main thread      1=main can be thread, 0=not available
#define osFeature_Pool         1       ///< Memory Pools:    1=available, 0=not available
#define osFeature_MailQ        1       ///< Mail Queues:     1=available, 0=not available
#define osFeature_MessageQ     1       ///< Message Queues:  1=available, 0=not available
#define osFeature_Signals      0       ///< maximum number of Signal Flags available per thread
#define osFeature_Semaphore    30       ///< maximum count for \ref osSemaphoreCreate function
#define osFeature_Wait         0       ///< osWait function: 1=available, 0=not available
#define osFeature_SysTick      1       ///< osKernelSysTick functions: 1=available, 0=not available

2.1. Kernel Information and Control

• osKernelInitialize

osStatus osKernelInitialize(void);

Return value: status code

• osKernelStart

osStatus osKernelStart(void);

Return value: status code

• osKernelRunning

int32_t osKernelRunning(void);

Return value: 0 indicates RTOS not started, 1 indicates RTOS has started

• osKernelSysTick

uint32_t osKernelSysTick(void);

Return value: current time of the RTOS kernel system

2.2. Thread Management

❝

The ## connector is used to concatenate two strings into one string.

❞

The CMSIS-RTOS API stores the structure for managing thread parameters as follows:

typedef struct os_thread_def {
    char           *name;       ///< Thread name
    os_pthread      pthread;    ///< start address of thread function
    osPriority      tpriority;  ///< initial thread priority
    uint32_t        instances;  ///< maximum number of instances of that thread function
    k_stack_t      *stackbase;  ///< base address of task
    uint32_t        stacksize;  ///< stack size requirements in bytes; 0 is default stack size
    k_timeslice_t   timeslice;  ///< timeslice
    k_task_t       *task;
} osThreadDef_t;

The macro defined for creating threads in the CMSIS-RTOS API is as follows:

#define osThreadDef(name, priority, instances, stacksz)  \
    k_task_t task_handler_##name; \
    k_stack_t task_stack_##name[(stacksz)]; \
    const osThreadDef_t os_thread_def_##name = \
        { #name, (os_pthread)(name), (osPriority)(priority), (instances), \
        (&((task_stack_##name)[0])), (stacksz), ((k_timeslice_t)0u), (&(task_handler_##name)) }

❝

The instances in the macro definition indicate how many task instances are created based on this task parameter. For example, if instances are 2, two tasks will be created.

❞

The macro defined for obtaining the thread parameter structure in the CMSIS-RTOS API is as follows:

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

The APIs for managing thread parameters are as follows:

• osThreadCreate

osThreadId osThreadCreate(const osThreadDef_t *thread_def, void *argument);

Where osThreadId is defined as a pointer type to k_task_t:

typedef k_task_t *osThreadId;

Return value: pointer of the task control block type in TencentOS-tiny.

• osThreadTerminate

osStatus osThreadTerminate(osThreadId thread_id);

Return value: osStatus

• osThreadYield

osStatus osThreadYield(void);

Return value: osStatus

• osThreadGetID

osThreadId osThreadGetId(void);

• osThreadSetPriority

osStatus osThreadSetPriority(osThreadId thread_id, osPriority priority);

• osThreadGetPriority

osPriority osThreadGetPriority(osThreadId thread_id);

❝

It is important to note that in TencentOS-tiny, after calling the priority options setting provided by the CMSIS-RTOS API, the actual set task value is different.

❞

The thread priority macros defined by the CMSIS-RTOS API are as follows:

typedef enum {
    osPriorityIdle          = -3,          ///< priority: idle (lowest)
    osPriorityLow           = -2,          ///< priority: low
    osPriorityBelowNormal   = -1,          ///< priority: below normal
    osPriorityNormal        =  0,          ///< priority: normal (default)
    osPriorityAboveNormal   = +1,          ///< priority: above normal
    osPriorityHigh          = +2,          ///< priority: high
    osPriorityRealtime      = +3,          ///< priority: realtime (highest)
    osPriorityError         = 0x84        ///< system cannot determine priority or thread has illegal priority
} osPriority;

During the implementation in TencentOS-tiny, the conversion was done as follows:

static k_prio_t priority_cmsis2knl(osPriority prio)
{
    if (prio == osPriorityError) {
        return K_TASK_PRIO_INVALID;
    }

    return (k_prio_t)(3 - prio);
}

static osPriority priority_knl2cmsis(k_prio_t prio)
{
    return (osPriority)(3 - prio);
}

For example, if the thread is created with osPriorityNormal=0, the “actual set task priority is 3”.

2.3. General Wait Functions

The wait function APIs provided by CMSIS-RTOS are as follows:

• osDelay

osStatus osDelay(uint32_t millisec);

Return value: osStatus.

2.4. Software Timer Management

The structure for storing timer parameters provided by the CMSIS-RTOS API is as follows:

typedef struct os_timer_def {
    os_ptimer                 cb;   ///< start address of a timer function
    k_timer_t                *timer;
} osTimerDef_t;

The macro definition for creating a software timer provided by the CMSIS-RTOS API is as follows:

#define osTimerDef(name, function)  \
    k_timer_t timer_handler_##name; \
    const osTimerDef_t os_timer_def_##name = \
        { (os_ptimer)(function), (&(timer_handler_##name)) }

The macro for obtaining the software timer parameter structure defined by the CMSIS-RTOS API is as follows:

#define osTimer(name) \
    &os_timer_def_##name

The software timer management APIs provided by CMSIS-RTOS are as follows:

• osTimerCreate

osTimerId osTimerCreate(const osTimerDef_t *timer_def, os_timer_type type, void *argument);

Where osTimerId is defined as a pointer type to k_timer_t:

typedef k_timer_t *osTimerId;

The type parameter is of os_timer_type type, indicating whether the software timer is one-shot or periodic:

typedef enum  {
    osTimerOnce             =     0,       ///< one-shot timer
    osTimerPeriodic         =     1        ///< repeating timer
} os_timer_type;

• osTimerStart

osStatus osTimerStart(osTimerId timer_id, uint32_t millisec);

Return value: osStatus.

• osTimerStop

osStatus osTimerStop(osTimerId timer_id)

Return value: osStatus.

• osTimerDelete

osStatus osTimerDelete(osTimerId timer_id);

Return value: osStatus.

2.5. Semaphore Management

The structure for storing semaphore parameters provided by the CMSIS-RTOS API is as follows:

typedef struct os_semaphore_def {
    uint32_t                    dummy;  ///< dummy value.
    k_sem_t                    *sem;
} osSemaphoreDef_t;

The macro definition for creating a semaphore provided by the CMSIS-RTOS API is as follows:

#define osSemaphoreDef(name)  \
    k_sem_t sem_handler_##name; \
    const osSemaphoreDef_t os_semaphore_def_##name = { 0, (&(sem_handler_##name)) }

The macro for obtaining the semaphore parameter structure defined by the CMSIS-RTOS API is as follows:

#define osSemaphore(name)  \
    &os_semaphore_def_##name

The semaphore management APIs provided by CMSIS-RTOS are as follows:

• osSemaphoreCreate

osSemaphoreId osSemaphoreCreate(const osSemaphoreDef_t *semaphore_def, int32_t count);

Where osSemaphoreId is defined as a pointer type to k_sem_t:

typedef k_sem_t *osSemaphoreId;

• osSemaphoreWait

int32_t osSemaphoreWait(osSemaphoreId semaphore_id, uint32_t millisec);

Return value: int32_t, normally returns the current count, returns -1 on failure.

If blocking delay is required, the parameter should be set to the macro definition osWaitForever provided by the CMSIS-RTOS API:

#define osWaitForever     0xFFFFFFFF     ///< wait forever timeout value

• osSemaphoreRelease

osStatus osSemaphoreRelease(osSemaphoreId semaphore_id);

Return value: osStatus.

• osSemaphoreDelete

osStatus osSemaphoreDelete(osSemaphoreId semaphore_id);

Return value: osStatus.

2.6. Mutex Management

The structure for storing mutex parameters provided by the CMSIS-RTOS API is as follows:

typedef struct os_mutex_def {
    uint32_t                    dummy;  ///< dummy value.
    k_mutex_t                  *mutex;
} osMutexDef_t;

The macro definition for creating a mutex provided by the CMSIS-RTOS API is as follows:

#define osMutexDef(name)  \
    k_mutex_t mutex_handler_##name; \
    const osMutexDef_t os_mutex_def_##name = { 0, (&(mutex_handler_##name)) }

The macro for obtaining the mutex parameter structure defined by the CMSIS-RTOS API is as follows:

#define osMutex(name)  \
    &os_mutex_def_##name

The mutex management APIs provided by CMSIS-RTOS are as follows:

• osMutexCreate

osMutexId osMutexCreate(const osMutexDef_t *mutex_def);

Where osMutexId is defined as a pointer type to k_mutex_t:

typedef k_mutex_t *osMutexId;

• osMutexWait

osStatus osMutexWait(osMutexId mutex_id, uint32_t millisec);

Return value: osStatus.

If blocking delay is required, the parameter should be set to the macro definition osWaitForever provided by the CMSIS-RTOS API:

#define osWaitForever     0xFFFFFFFF     ///< wait forever timeout value

• osMutexRelease

osStatus osMutexRelease(osMutexId mutex_id);

Return value: osStatus.

• osMutexDelete

osStatus osMutexDelete(osMutexId mutex_id);

Return value: osStatus.

2.7. Static Memory Pool Management

The structure for storing static memory pool parameters provided by the CMSIS-RTOS API is as follows:

typedef struct os_pool_def {
    uint32_t                    pool_sz;    ///< number of items (elements) in the pool
    uint32_t                    item_sz;    ///< size of an item
    void                       *pool;       ///< pointer to memory for pool
    k_mmblk_pool_t             *mmblk_pool; ///< memory blk pool handler
} osPoolDef_t;

The macro definition for creating a mutex provided by the CMSIS-RTOS API is as follows:

#define osPoolDef(name, no, type)   \
    k_mmblk_pool_t mmblk_pool_handler_##name; \
    uint8_t mmblk_pool_buf_##name[(no) * sizeof(type)]; \
    const osPoolDef_t os_pool_def_##name = \
        { (no), sizeof(type), (&((mmblk_pool_buf_##name)[0])), (&(mmblk_pool_handler_##name)) }

The macro for obtaining the mutex parameter structure defined by the CMSIS-RTOS API is as follows:

#define osPool(name) \
 &os_pool_def_##name

The mutex management APIs provided by CMSIS-RTOS are as follows:

• osPoolCreate

osPoolId osPoolCreate(const osPoolDef_t *pool_def);

Where osPoolId is defined as a pointer type to k_mmblk_pool_t:

typedef k_mmblk_pool_t *osPoolId;

• osPoolAlloc

void *osPoolAlloc(osPoolId pool_id);

• osPoolCAlloc

void *osPoolCAlloc(osPoolId pool_id);

• osPoolFree

osStatus osPoolFree(osPoolId pool_id, void *block);

Return value: osStatus.

2.8. Message Queue Management

The structure for storing message queue parameters provided by the CMSIS-RTOS API is as follows:

typedef struct os_messageQ_def {
    uint32_t                    queue_sz;   ///< number of elements in the queue
    uint32_t                    item_sz;    ///< size of an item
    void                       *pool;       ///< memory array for messages
    k_msg_q_t                  *queue;      ///< queue handler
} osMessageQDef_t;

The macro definition for creating a message queue provided by the CMSIS-RTOS API is as follows:

#define osMessageQDef(name, queue_sz, type)   \
    k_msg_q_t msg_q_handler_##name; \
    const osMessageQDef_t os_messageQ_def_##name = \
        { (queue_sz), sizeof(type), NULL, (&(msg_q_handler_##name)) }

The macro for obtaining the message queue parameter structure defined by the CMSIS-RTOS API is as follows:

#define osMessageQ(name) \
    &os_messageQ_def_##name

The message queue management APIs provided by CMSIS-RTOS are as follows:

• osMessageCreate

osMessageQId osMessageCreate(const osMessageQDef_t *queue_def, osThreadId thread_id);

Where osMessageQId is defined as a pointer type to k_msg_q_t:

typedef k_msg_q_t *osMessageQId;

• osMessagePut

osStatus osMessagePut(osMessageQId queue_id, uint32_t info, uint32_t millisec);

Return value: osStatus.

❝

Due to the different implementation mechanisms of the message queue in TencentOS-tiny, the millisec parameter in this API is not used.

❞

• osMessageGet

osEvent osMessageGet(osMessageQId queue_id, uint32_t millisec);

Return value: osEvent, which contains event information and error code, as well as the value received by the message queue.

If blocking delay is required, the parameter should be set to the macro definition osWaitForever provided by the CMSIS-RTOS API:

#define osWaitForever     0xFFFFFFFF     ///< wait forever timeout value

3. Usage Examples

3.1. Task Creation Example

#include <cmsis_os.h>

void task1_entry(void *arg)
{
    while(1)
    {
        printf("task1 is running...\r\n");
        osDelay(1000);
    }
}
osThreadDef(task1_entry, osPriorityNormal, 1, 512);

void task2_entry(void *arg)
{
    while(1)
    {
        printf("task2 is running...\r\n");
        osDelay(1000);
    }
}
osThreadDef(task2_entry, osPriorityNormal, 1, 512);

void application_entry(void *arg)
{
    osThreadCreate(osThread(task1_entry), NULL);
    osThreadCreate(osThread(task2_entry), NULL);
    return;
}

The task running results are as follows:

task1 is running...
task2 is running...
task1 is running...
task2 is running...
task1 is running...
task2 is running...

3.2. Software Timer Usage Example

#include <cmsis_os.h>

void timer1_cb(void *arg)
{
    printf("timer1 is timeout!\r\n");
}

void timer2_cb(void *arg)
{
    printf("timer2 is timeout!\r\n");
}

osTimerDef(timer1, timer1_cb);
osTimerDef(timer2, timer2_cb);

void application_entry(void *arg)
{
    osTimerId timer1;
    osTimerId timer2;
    
    timer1 = osTimerCreate(osTimer(timer1), osTimerOnce, NULL);
    timer2 = osTimerCreate(osTimer(timer2), osTimerPeriodic, NULL);
    
    osTimerStart(timer1, 5000);
    osTimerStart(timer2, 1000);
    
    return;
}

The running results are as follows:

timer2 is timeout!
timer2 is timeout!
timer2 is timeout!
timer2 is timeout!
timer1 is timeout!
timer2 is timeout!
timer2 is timeout!
timer2 is timeout!
timer2 is timeout!

3.3. Semaphore Usage Example

#include <cmsis_os.h>

osSemaphoreId sync_sem_id;
osSemaphoreDef(sync_sem);

void task1_entry(void *arg)
{
    while(1)
    {
        printf("task1 is waiting sem forever...\r\n");
        osSemaphoreWait(sync_sem_id, osWaitForever);
        printf("task1 get sem!\r\n");
    }
}
osThreadDef(task1_entry, osPriorityNormal, 1, 512);

void task2_entry(void *arg)
{
    while(1)
    {
        printf("task2 will release a sem...\r\n");
        osSemaphoreRelease(sync_sem_id);
        osDelay(1000);
    }
}
osThreadDef(task2_entry, osPriorityNormal, 1, 512);

void application_entry(void *arg)
{
    sync_sem_id = osSemaphoreCreate(osSemaphore(sync_sem), 0);

    osThreadCreate(osThread(task1_entry), NULL);
    osThreadCreate(osThread(task2_entry), NULL);
    
    return;
}

The running results are:

task1 is waiting sem forever...
task1 get sem!
task1 is waiting sem forever...
task2 will release a sem...
task1 get sem!
task1 is waiting sem forever...
task2 will release a sem...
task1 get sem!
task1 is waiting sem forever...
task2 will release a sem...
task1 get sem!
task1 is waiting sem forever...
task2 will release a sem...
task1 get sem!
task1 is waiting sem forever...

3.4. Mutex Usage Example

#include <cmsis_os.h>

osMutexId sync_mutex_id;
osMutexDef(sync_mutex);

void task1_entry(void *arg)
{
    while(1)
    {
        osMutexWait(sync_mutex_id, osWaitForever);
        
        printf("task1 get mutex,doing sth...\r\n");
        HAL_Delay(1000);    // Busy loop occupying CPU
        printf("task1 finish do sth!\r\n");
        
        osMutexRelease(sync_mutex_id);
        
        osDelay(1000);
    }
}
osThreadDef(task1_entry, osPriorityHigh, 1, 512);

void task2_entry(void *arg)
{
    while(1)
    {
        osMutexWait(sync_mutex_id, osWaitForever);
        
        printf("task2 get mutex,doing sth...\r\n");
        HAL_Delay(2000);    // Busy loop occupying CPU
        printf("task2 finish do sth!\r\n");
        
        osMutexRelease(sync_mutex_id);
        
        osDelay(1000);
    }
}
osThreadDef(task2_entry, osPriorityNormal, 1, 512);

void application_entry(void *arg)
{
    sync_mutex_id = osMutexCreate(osMutex(sync_mutex));

    osThreadCreate(osThread(task1_entry), NULL);
    osThreadCreate(osThread(task2_entry), NULL);
    
    return;
}

The running results are:

task1 get mutex,doing sth...
task1 finish do sth!
task2 get mutex,doing sth...
task2 finish do sth!
task1 get mutex,doing sth...
task1 finish do sth!
task1 get mutex,doing sth...
task1 finish do sth!
task2 get mutex,doing sth...

3.5. Dynamic Memory Usage Example

#include <cmsis_os.h>

typedef struct blk_st {
    int   id;
    char* payload;
} blk_t;

#define MMBLK_BLK_NUM 10

osPoolDef (MemPool, MMBLK_BLK_NUM, blk_t);
osPoolId mem_pool_id;

void task1_entry(void *arg)
{   
    blk_t *ptr = NULL;
    osStatus err;
    
    /* Print the size of a block */
    printf("block size is %d bytes\r\n", sizeof(blk_t));
    
    /* Request a block */
    ptr = osPoolAlloc(mem_pool_id);
    if (ptr == NULL) {
        printf("a mmblk alloc fail\r\n");
        return;
    }
    else {
        printf("a mmblk alloc success\r\n");
    }
    
    /* Use the block */
    ptr->id = 1;
    ptr->payload = "hello";
    printf("mmblk id:%d payload:%s\r\n", ptr->id, ptr->payload);
    
    /* Release after use */
    err = osPoolFree(mem_pool_id, ptr);
    if (err != osOK) {
        printf("a mmblk free fail, err = %d\r\n", err);
        return;
    }
    else {
        printf("a mmblk free success\r\n");
    }
    
    while (1) {
        tos_task_delay(1000);
    }
}

#define STK_SIZE_TASK1      1024
osThreadDef(task1_entry, osPriorityNormal, 1, STK_SIZE_TASK1);

void application_entry(void *arg)
{
    // Initialize static memory pool
    mem_pool_id = osPoolCreate(osPool(MemPool));
    if (mem_pool_id == NULL) {
        printf("mmblk pool create fail\r\n");
        return;
    }
    else {
        printf("mmblk pool create success\r\n");
    }

    // Create task
    osThreadCreate(osThread(task1_entry), NULL);

    return;
}

The running results are:

mmblk pool create success
block size is 8 bytes
a mmblk alloc success
mmblk id:1 payload:hello
a mmblk free success

3.6. Message Queue Usage Example

#include <cmsis_os.h>

#define STK_SIZE_TASK_RECEIVER      512
#define STK_SIZE_TASK_SENDER        512

#define MESSAGE_MAX     10

osMessageQId msg_q_id;
osMessageQDef(msg_q,MESSAGE_MAX,uint32_t);

void task_receiver_entry(void *arg)
{
    osEvent event;
    osStatus ret;
    uint32_t value;

    while (1)
    {
        event = osMessageGet(msg_q_id, osWaitForever);
        ret = event.status;
        if (ret == osOK)
        {
            value = event.value.v;
            printf("receiver: msg incoming[%s]\r\n", (char*)value);
        }
    }
}
osThreadDef(task_receiver_entry, osPriorityNormal, 1, STK_SIZE_TASK_RECEIVER);

void task_sender_entry(void *arg)
{
    char *msg_prio_0 = "msg 0";
    char *msg_prio_1 = "msg 1";
    char *msg_prio_2 = "msg 2";

    printf("sender: post a messgae:[%s]\r\n", msg_prio_2);
    osMessagePut(msg_q_id,(uint32_t)msg_prio_2,0);
    
    printf("sender: post a messgae:[%s]\r\n", msg_prio_1);
    osMessagePut(msg_q_id,(uint32_t)msg_prio_1,0);
    
    printf("sender: post a messgae:[%s]\r\n", msg_prio_0);
    osMessagePut(msg_q_id,(uint32_t)msg_prio_0,0);

}
osThreadDef(task_sender_entry, osPriorityNormal, 1, STK_SIZE_TASK_SENDER);

void application_entry(void *arg)
{
    msg_q_id = osMessageCreate(osMessageQ(msg_q),NULL);

    osThreadCreate(osThread(task_receiver_entry), NULL);
    osThreadCreate(osThread(task_sender_entry), NULL);
    
    return;
}

The running results are:

sender: post a messgae:[msg 2]
sender: post a messgae:[msg 1]
sender: post a messgae:[msg 0]
receiver: msg incoming[msg 2]
receiver: msg incoming[msg 1]
receiver: msg incoming[msg 0]

Differences Between
and
in Text or Code

Several Open Source Editor Tools Similar to VS Code

CRC Calculation Unit in STM32 and Applications of CRC Verification

Long press to go to the public account included in the image to follow