如何理解CMSIS-RTOS API和宏定義
CMSIS-RTOS API是ARM公司為RTOS內核制定的一套通用接口協議，它提供了一套「標準的API接口」，可以移植到各種各樣的RTOS上，使得上層的軟件、中間件、庫以及其他組件在不同的RTOS之上都可以正常工作。
這套API表現為兩個文件：cmsis-os.h和cmsis-os.c，也就是說，不同的RTOS內核分別用自己的一套東西去適配.c文件中的接口，而用戶只需要調用.h文件中給出的API編寫應用。
本文會列舉性的給出CMSIS-RTOS有哪些API和宏定義，并給出每類API的使用demo，學習者只需要了解這些東西，能看懂用CMSIS-RTOS API編寫的應用程序即可~
基于TencentOS-tiny的CMSIS-RTOS API v1.02版本實現：
cmsis_os.h
cmsis_os.c
基于TencentOS-tiny的CMSIS-RTOS API v2.1.3版本實現：
cmsis_os2.h
cmsis_os2.c
CMSIS-RTOS API的整體架構如下圖：
2. CMSIS-RTOS API列表
下面列出了 CMSIS-RTOS API v1.02 版本提供的所有API。
CMSIS-RTOS 所有API使用的錯誤碼（cmsis-os.h）：
typedefenum{
osOK=0,///CMSIS-RTOS API一些可選項控制是否開啟（cmsis-os.h）：
#defineosFeature_MainThread1///
#defineosFeature_Pool1///2.1. 內核信息和控制
| API | 描述 |
|---|---|
| osKernelInitialize | 初始化RTOS內核 |
| osKernelStart | 啟動RTOS內核 |
| osKernelRunning | Query if the RTOS kernel is running |
| osKernelSysTick (可選) | Get RTOS kernel system timer counter |
| osKernelSysTickFrequency (可選) | RTOS kernel system timer frequency in Hz |
| osKernelSysTickMicroSec (可選) | Convert microseconds value to RTOS kernel system timer value |
osKernelInitialize
osStatusosKernelInitialize(void);
返回值：status code
osKernelStart
osStatusosKernelStart(void);
返回值：status code
osKernelRunning
int32_tosKernelRunning(void);
返回值：0表示RTOS未啟動，1表示RTOS已經啟動
osKernelSysTick
uint32_tosKernelSysTick(void);
返回值：RTOS內核系統當前的時間
2.2. 線程管理
?
##連接符的作用是連接兩個字符串，合為一個字符串。
?
CMSIS-RTOS API 存放線程參數管理的結構體如下：typedefstructos_thread_def{
char*name;///CMSIS-RTOS API 定義線程的宏如下：
#defineosThreadDef(name,priority,instances,stacksz)
k_task_ttask_handler_##name; k_stack_ttask_stack_##name[(stacksz)]; constosThreadDef_tos_thread_def_##name= {#name,(os_pthread)(name),(osPriority)(priority),(instances), (&((task_stack_##name)[0])),(stacksz),((k_timeslice_t)0u),(&(task_handler_##name))}?
宏定義中的 instances 表示基于此任務參數，創建出幾個任務實例，比如instances為2，則會創建出兩個任務。
?
CMSIS-RTOS API定義的獲取線程參數結構體的宏如下：
#defineosThread(name)
&os_thread_def_##name管理線程參數的API如下：
| API | 描述 |
|---|---|
| osThreadCreate | 創建線程并開始執行 |
| osThreadTerminate | 停止線程執行 |
| osThreadYield | 線程主動讓出 |
| osThreadGetID | 獲取當前正在運行線程的ID |
| osThreadSetPriority | 改變線程優先級 |
| osThreadGetPriority | 獲取線程優先級 |
osThreadCreate
osThreadIdosThreadCreate(constosThreadDef_t*thread_def,void*argument);
其中osThreadId被定義為k_task_t指針類型：typedefk_task_t*osThreadId;
返回值：TencentOS-tiny中的任務控制塊類型指針。
osThreadTerminate
osStatusosThreadTerminate(osThreadIdthread_id);
返回值：osStatus
osThreadYield
osStatusosThreadYield(void);
返回值：osStatus
osThreadGetID
osThreadIdosThreadGetId(void);
osThreadSetPriority
osStatusosThreadSetPriority(osThreadIdthread_id,osPrioritypriority);
osThreadGetPriority
osPriorityosThreadGetPriority(osThreadIdthread_id);
?
使用時需要特別注意，在TencentOS-tiny中，調用CMSIS-RTOS API提供的優先級選項設置之后，實際設置的任務值是不同的。
?
CMSIS-RTOS API提供的線程優先級宏定義如下：
typedefenum{
osPriorityIdle=-3,///statick_prio_tpriority_cmsis2knl(osPriorityprio)
{ if(prio==osPriorityError){ returnK_TASK_PRIO_INVALID; } return(k_prio_t)(3-prio); } staticosPrioritypriority_knl2cmsis(k_prio_tprio) { return(osPriority)(3-prio); }比如創建線程時設置為 osPriorityNormal=0，則「實際設置的任務優先級為3」。
2.3. 通用等待函數
CMSIS-RTOS提供的等待函數API如下：
| API | 描述 |
|---|---|
| osDelay | 等待指定的時間 |
| osWait（可選） | 等待信號、消息、郵箱的某個事件 |
osDelay
osStatusosDelay(uint32_tmillisec);
返回值：osStatus。
2.4. 軟件定時器管理
CMSIS-RTOS API提供的存儲定時器參數的結構體如下：typedefstructos_timer_def{
os_ptimercb;///CMSIS-RTOS API提供的定義一個軟件定時器的宏定義如下：
#defineosTimerDef(name,function)
k_timer_ttimer_handler_##name; constosTimerDef_tos_timer_def_##name= {(os_ptimer)(function),(&(timer_handler_##name))}CMSIS-RTOS API定義的獲取軟件定時器參數結構體的宏如下：
#defineosTimer(name)
&os_timer_def_##nameCMSIS-RTOS API提供的軟件定時器管理API如下：
| API | 描述 |
|---|---|
| osTimerCreate | 創建一個軟件定時器 |
| osTimerStart | 啟動軟件定時器 |
| osTimerStop | 停止軟件定時器 |
| osTimerDelete | 刪除軟件定時器 |
osTimerCreate
osTimerIdosTimerCreate(constosTimerDef_t*timer_def,os_timer_typetype,void*argument);
其中osTimerId被定義為k_timer_t指針類型：
typedefk_timer_t*osTimerId;
type參數為 os_timer_type 類型，表示軟件定時器的類型為單次觸發或者周期觸發：
typedefenum{
osTimerOnce=0,///osTimerStart
osStatusosTimerStart(osTimerIdtimer_id,uint32_tmillisec);
返回值：osStatus。
osTimerStop
osStatusosTimerStop(osTimerIdtimer_id)
返回值：osStatus。
osTimerDelete
osStatusosTimerDelete(osTimerIdtimer_id);
返回值：osStatus。
2.5. 信號量管理
CMSIS-RTOS API提供的存儲信號量參數的結構體如下：
typedefstructos_semaphore_def{
uint32_tdummy;///CMSIS-RTOS API提供的定義一個信號量的宏定義如下：
#defineosSemaphoreDef(name)
k_sem_tsem_handler_##name; constosSemaphoreDef_tos_semaphore_def_##name={0,(&(sem_handler_##name))}CMSIS-RTOS API定義的獲取信號量參數結構體的宏如下：
#defineosSemaphore(name)
&os_semaphore_def_##nameCMSIS-RTOS API提供的信號量管理API如下：
| API | 描述 |
|---|---|
| osSemaphoreCreate | 創建一個信號量 |
| osSemaphoreWait | 等待信號量 |
| osSemaphoreRelease | 釋放信號量 |
| osSemaphoreDelete | 刪除信號量 |
osSemaphoreCreate
osSemaphoreIdosSemaphoreCreate(constosSemaphoreDef_t*semaphore_def,int32_tcount);
其中 osSemaphoreId 被定義為k_sem_t指針類型：
typedefk_sem_t*osSemaphoreId;
osSemaphoreWait
int32_tosSemaphoreWait(osSemaphoreIdsemaphore_id,uint32_tmillisec);
返回值：int32_t ，正常返回當前count數，失敗返回-1。
如果需要阻塞延時，參數應該設置為CMSIS-RTOS API提供的宏定義 osWaitForever ：
#defineosWaitForever0xFFFFFFFF///
osSemaphoreRelease
osStatusosSemaphoreRelease(osSemaphoreIdsemaphore_id);
返回值：osStatus。
osSemaphoreDelete
osStatusosSemaphoreDelete(osSemaphoreIdsemaphore_id);
返回值：osStatus。
2.6. 互斥鎖管理
CMSIS-RTOS API提供的存儲互斥鎖參數的結構體如下：
typedefstructos_mutex_def{
uint32_tdummy;///CMSIS-RTOS API提供的定義一個互斥鎖的宏定義如下：
#defineosMutexDef(name)
k_mutex_tmutex_handler_##name; constosMutexDef_tos_mutex_def_##name={0,(&(mutex_handler_##name))}CMSIS-RTOS API定義的獲取互斥鎖參數結構體的宏如下：
#defineosMutex(name)
&os_mutex_def_##nameCMSIS-RTOS API提供的互斥鎖管理API如下：
| API | 描述 |
|---|---|
| osMutexCreate | 創建一個互斥鎖 |
| osMutexWait | 等待獲取互斥鎖 |
| osMutexRelease | 釋放互斥鎖 |
| osMutexDelete | 刪除互斥鎖 |
osMutexCreate
osMutexIdosMutexCreate(constosMutexDef_t*mutex_def);
其中 osMutexId 被定義為k_mutex_t指針類型：
typedefk_mutex_t*osMutexId;
osMutexWait
osStatusosMutexWait(osMutexIdmutex_id,uint32_tmillisec);
返回值：osStatus 。
如果需要阻塞延時，參數應該設置為CMSIS-RTOS API提供的宏定義 osWaitForever ：
#defineosWaitForever0xFFFFFFFF///
osMutexRelease
osStatusosMutexRelease(osMutexIdmutex_id);
返回值：osStatus。
osMutexDelete
osStatusosMutexDelete(osMutexIdmutex_id);
返回值：osStatus。
2.7. 靜態內存池管理
CMSIS-RTOS API提供的存儲靜態內存池參數的結構體如下：
typedefstructos_pool_def{
uint32_tpool_sz;///CMSIS-RTOS API提供的定義一個互斥鎖的宏定義如下：
#defineosPoolDef(name,no,type)
k_mmblk_pool_tmmblk_pool_handler_##name; uint8_tmmblk_pool_buf_##name[(no)*sizeof(type)]; constosPoolDef_tos_pool_def_##name= {(no),sizeof(type),(&((mmblk_pool_buf_##name)[0])),(&(mmblk_pool_handler_##name))}CMSIS-RTOS API定義的獲取互斥鎖參數結構體的宏如下：
#defineosPool(name)
&os_pool_def_##nameCMSIS-RTOS API提供的互斥鎖管理API如下：
| API | 描述 |
|---|---|
| osPoolCreate | 創建一塊固定大小的靜態內存池 |
| osPoolAlloc | 申請分配內存 |
| osPoolCAlloc | 申請分配一塊內存并全部初始化為0 |
| osPoolFree | 申請回收內存 |
osPoolCreate
osPoolIdosPoolCreate(constosPoolDef_t*pool_def);
其中 osPoolId 被定義為 k_mmblk_pool_t 指針類型：
typedefk_mmblk_pool_t*osPoolId;
osPoolAlloc
void*osPoolAlloc(osPoolIdpool_id);
osPoolCAlloc
void*osPoolCAlloc(osPoolIdpool_id);
osPoolFree
osStatusosPoolFree(osPoolIdpool_id,void*block);
返回值：osStatus。
2.8. 消息隊列管理
CMSIS-RTOS API提供的存儲消息隊列參數的結構體如下：
typedefstructos_messageQ_def{
uint32_tqueue_sz;///CMSIS-RTOS API提供的定義一個消息隊列的宏定義如下：
#defineosMessageQDef(name,queue_sz,type)
k_msg_q_tmsg_q_handler_##name; constosMessageQDef_tos_messageQ_def_##name= {(queue_sz),sizeof(type),NULL,(&(msg_q_handler_##name))}CMSIS-RTOS API定義的獲取消息隊列參數結構體的宏如下：
#defineosMessageQ(name)
&os_messageQ_def_##nameCMSIS-RTOS API提供的消息隊列管理API如下：
| API | 描述 |
|---|---|
| osMessageCreate | 初始化一個消息隊列 |
| osMessagePut | 向消息隊列中加入數據 |
| osMessageGet | 從消息隊列中取出數據 |
osMessageCreate
osMessageQIdosMessageCreate(constosMessageQDef_t*queue_def,osThreadIdthread_id);
其中 osMessageQId 被定義為 k_msg_q_t 指針類型：
typedefk_msg_q_t*osMessageQId;
osMessagePut
osStatusosMessagePut(osMessageQIdqueue_id,uint32_tinfo,uint32_tmillisec);
返回值：osStatus 。
?
因為TencentOS-tiny中消息隊列實現機制的不同，此API中的 millisec 參數未用到。
?
osMessageGet
osEventosMessageGet(osMessageQIdqueue_id,uint32_tmillisec);
返回值：osEvent ，其中包含了事件信息和錯誤碼，以及消息隊列收到的值。
如果需要阻塞延時，參數應該設置為CMSIS-RTOS API提供的宏定義 osWaitForever ：
#defineosWaitForever0xFFFFFFFF///
3. 使用示例
3.1. 任務創建示例
#include
voidtask1_entry(void*arg) { while(1) { printf("task1isrunning... "); osDelay(1000); } } osThreadDef(task1_entry,osPriorityNormal,1,512); voidtask2_entry(void*arg) { while(1) { printf("task2isrunning... "); osDelay(1000); } } osThreadDef(task2_entry,osPriorityNormal,1,512); voidapplication_entry(void*arg) { osThreadCreate(osThread(task1_entry),NULL); osThreadCreate(osThread(task2_entry),NULL); return; }
任務運行結果如下：
task1isrunning... task2isrunning... task1isrunning... task2isrunning... task1isrunning... task2isrunning...
3.2. 軟件定時器使用示例
#includevoidtimer1_cb(void*arg) { printf("timer1istimeout! "); } voidtimer2_cb(void*arg) { printf("timer2istimeout! "); } osTimerDef(timer1,timer1_cb); osTimerDef(timer2,timer2_cb); voidapplication_entry(void*arg) { osTimerIdtimer1; osTimerIdtimer2; timer1=osTimerCreate(osTimer(timer1),osTimerOnce,NULL); timer2=osTimerCreate(osTimer(timer2),osTimerPeriodic,NULL); osTimerStart(timer1,5000); osTimerStart(timer2,1000); return; }
運行結果如下：
timer2istimeout! timer2istimeout! timer2istimeout! timer2istimeout! timer1istimeout! timer2istimeout! timer2istimeout! timer2istimeout! timer2istimeout!
3.3. 信號量使用示例
#includeosSemaphoreIdsync_sem_id; osSemaphoreDef(sync_sem); voidtask1_entry(void*arg) { while(1) { printf("task1iswaitingsemforever... "); osSemaphoreWait(sync_sem_id,osWaitForever); printf("task1getsem! "); } } osThreadDef(task1_entry,osPriorityNormal,1,512); voidtask2_entry(void*arg) { while(1) { printf("task2willreleaseasem... "); osSemaphoreRelease(sync_sem_id); osDelay(1000); } } osThreadDef(task2_entry,osPriorityNormal,1,512); voidapplication_entry(void*arg) { sync_sem_id=osSemaphoreCreate(osSemaphore(sync_sem),0); osThreadCreate(osThread(task1_entry),NULL); osThreadCreate(osThread(task2_entry),NULL); return; }
運行結果為：
task1iswaitingsemforever... task1getsem! task1iswaitingsemforever... task2willreleaseasem... task1getsem! task1iswaitingsemforever... task2willreleaseasem... task1getsem! task1iswaitingsemforever... task2willreleaseasem... task1getsem! task1iswaitingsemforever... task2willreleaseasem... task1getsem! task1iswaitingsemforever...
3.4. 互斥鎖使用示例
#include
osMutexIdsync_mutex_id;
osMutexDef(sync_mutex);
voidtask1_entry(void*arg)
{
while(1)
{
osMutexWait(sync_mutex_id,osWaitForever);
printf("task1getmutex,doingsth...
");
HAL_Delay(1000);//死循環占用CPU
printf("task1finishdosth!
");
osMutexRelease(sync_mutex_id);
osDelay(1000);
}
}
osThreadDef(task1_entry,osPriorityHigh,1,512);
voidtask2_entry(void*arg)
{
while(1)
{
osMutexWait(sync_mutex_id,osWaitForever);
printf("task2getmutex,doingsth...
");
HAL_Delay(2000);//死循環占用CPU
printf("task2finishdosth!
");
osMutexRelease(sync_mutex_id);
osDelay(1000);
}
}
osThreadDef(task2_entry,osPriorityNormal,1,512);
voidapplication_entry(void*arg)
{
sync_mutex_id=osMutexCreate(osMutex(sync_mutex));
osThreadCreate(osThread(task1_entry),NULL);
osThreadCreate(osThread(task2_entry),NULL);
return;
}
運行結果為：
task1getmutex,doingsth... task1finishdosth! task2getmutex,doingsth... task2finishdosth! task1getmutex,doingsth... task1finishdosth! task1getmutex,doingsth... task1finishdosth! task2getmutex,doingsth...
3.5. 動態內存使用示例
#includetypedefstructblk_st{ intid; char*payload; }blk_t; #defineMMBLK_BLK_NUM10 osPoolDef(MemPool,MMBLK_BLK_NUM,blk_t); osPoolIdmem_pool_id; voidtask1_entry(void*arg) { blk_t*ptr=NULL; osStatuserr; /*打印出一個塊的大小*/ printf("blocksizeis%dbytes ",sizeof(blk_t)); /*申請一個塊*/ ptr=osPoolAlloc(mem_pool_id); if(ptr==NULL){ printf("ammblkallocfail "); return; } else{ printf("ammblkallocsuccess "); } /*使用該塊*/ ptr->id=1; ptr->payload="hello"; printf("mmblkid:%dpayload:%s ",ptr->id,ptr->payload); /*使用完畢之后釋放*/ err=osPoolFree(mem_pool_id,ptr); if(err!=osOK){ printf("ammblkfreefail,err=%d ",err); return; } else{ printf("ammblkfreesuccess "); } while(1){ tos_task_delay(1000); } } #defineSTK_SIZE_TASK11024 osThreadDef(task1_entry,osPriorityNormal,1,STK_SIZE_TASK1); voidapplication_entry(void*arg) { //初始化靜態內存池 mem_pool_id=osPoolCreate(osPool(MemPool)); if(mem_pool_id==NULL){ printf("mmblkpoolcreatefail "); return; } else{ printf("mmblkpoolcreatesuccess "); } //創建任務 osThreadCreate(osThread(task1_entry),NULL); return; }
運行結果為：
mmblkpoolcreatesuccess blocksizeis8bytes ammblkallocsuccess mmblkid:1payload:hello ammblkfreesuccess
3.6. 消息隊列使用示例
#include#defineSTK_SIZE_TASK_RECEIVER512 #defineSTK_SIZE_TASK_SENDER512 #defineMESSAGE_MAX10 osMessageQIdmsg_q_id; osMessageQDef(msg_q,MESSAGE_MAX,uint32_t); voidtask_receiver_entry(void*arg) { osEventevent; osStatusret; uint32_tvalue; while(1) { event=osMessageGet(msg_q_id,osWaitForever); ret=event.status; if(ret==osOK) { value=event.value.v; printf("receiver:msgincoming[%s] ",(char*)value); } } } osThreadDef(task_receiver_entry,osPriorityNormal,1,STK_SIZE_TASK_RECEIVER); voidtask_sender_entry(void*arg) { char*msg_prio_0="msg0"; char*msg_prio_1="msg1"; char*msg_prio_2="msg2"; printf("sender:postamessgae:[%s] ",msg_prio_2); osMessagePut(msg_q_id,(uint32_t)msg_prio_2,0); printf("sender:postamessgae:[%s] ",msg_prio_1); osMessagePut(msg_q_id,(uint32_t)msg_prio_1,0); printf("sender:postamessgae:[%s] ",msg_prio_0); osMessagePut(msg_q_id,(uint32_t)msg_prio_0,0); } osThreadDef(task_sender_entry,osPriorityNormal,1,STK_SIZE_TASK_SENDER); voidapplication_entry(void*arg) { msg_q_id=osMessageCreate(osMessageQ(msg_q),NULL); osThreadCreate(osThread(task_receiver_entry),NULL); osThreadCreate(osThread(task_sender_entry),NULL); return; }
運行結果為：
sender:postamessgae:[msg2] sender:postamessgae:[msg1] sender:postamessgae:[msg0] receiver:msgincoming[msg2] receiver:msgincoming[msg1] receiver:msgincoming[msg0]
-
內核
+關注
關注
3文章
1416瀏覽量
41405 -
API
+關注
關注
2文章
1605瀏覽量
63994 -
CMSIS
+關注
關注
0文章
41瀏覽量
12321
原文標題：CMSIS RTOS API，內核通用API接口
文章出處：【微信號：strongerHuang，微信公眾號：strongerHuang】歡迎添加關注！文章轉載請注明出處。
發布評論請先 登錄
工商網監
評論