微型嵌入式實時操作系統(tǒng)SmallRTOS常用接口函數(shù)和示例程序

微型嵌入式實時操作系統(tǒng)SmallRTOS是一個源代碼開放的、易于移植的、面向深度嵌入式應(yīng)用的微內(nèi)核實時操作系統(tǒng)，主要應(yīng)用領(lǐng)域為工業(yè)控制，智能傳感器開發(fā)，智能終端，物聯(lián)網(wǎng)等。任何人在遵循SmallRTOS許可協(xié)議的前提下均可免費使用該嵌入式實時操作系統(tǒng)。最新版本源代碼及示例工程的發(fā)布網(wǎng)站為：

下載到SmallRTOS的源代碼壓縮包后，進行解壓，可以看到SmallRTOS的目錄結(jié)構(gòu)如下：

Kernel： 存放SmallRTOS的內(nèi)核文件OS及和CPU相關(guān)的移植文件；
Demo： 存放SmallRTOS提供的示例文件；
Doc：存放SmallRTOS相關(guān)說明/教程文檔；
License：存放SmallRTOS使用許可；

微型嵌入式實時操作系統(tǒng)SmallRTOS在設(shè)計時，其文件命名、函數(shù)名及變量命名由專用的前綴進行區(qū)分：前綴為OS，表示為SmallRTOS的內(nèi)核，這些是與平臺無關(guān)的內(nèi)核部分，在進行跨平臺移植時，無需更改；前綴為Fit，表示為硬件（芯片類型等）相關(guān)的部分，在進行移植時，這一部分的文件、函數(shù)及變量需要根據(jù)硬件平臺（芯片類型等）進行適當?shù)恼{(diào)整；

微型嵌入式實時操作系統(tǒng)SmallRTOS是多任務(wù)搶占式操作系統(tǒng)，高優(yōu)先級任務(wù)可以搶先執(zhí)行，體現(xiàn)了操作系統(tǒng)的實時性。在SmallRTOS系統(tǒng)中，優(yōu)先級0為最低優(yōu)先級，該優(yōu)先級為SmallRTOS系統(tǒng)的保留優(yōu)先級，作為空閑任務(wù)OSIdleTask的專用優(yōu)先級，用戶創(chuàng)建的任務(wù)無法使用。除此之外的優(yōu)先級，用戶可以根據(jù)任務(wù)的重要程度自行分配使用。優(yōu)先級高的任務(wù)會搶先執(zhí)行。

為了突顯嵌入式操作系統(tǒng)配置的靈活性，在SmallRTOS系統(tǒng)設(shè)計之初就進行了全面的考量，部分參數(shù)采用了宏定義的方式進行配置。每個任務(wù)均有自己的名稱及優(yōu)先級，任務(wù)名稱長度最大為OSNAME_MAX_LEN， 該變量是一個宏定義，超出該最大長度的名稱會自動舍棄，默認為10個字符。任務(wù)優(yōu)先級的定義為OSTASK_MAX_PRIORITY， 這是一個非常重要的參數(shù)，系統(tǒng)默認值為10。

Ticks經(jīng)常被稱為時鐘滴答，是SmallRTOS系統(tǒng)中最小的時間單位，這個參數(shù)可以根據(jù)硬件平臺的性能進行設(shè)置。在SmallRTOS系統(tǒng)中，該參數(shù)采用宏定義configTICK_RATE_HZ進行配置。在SmallRTOS提供的大部分示例工程中，均配置的為1000Hz，即每個時鐘滴答間隔是1毫秒，該參數(shù)會影響SmallRTOS系統(tǒng)對任務(wù)的控制精度。系統(tǒng)調(diào)度器啟動后，會按照任務(wù)的優(yōu)先級進行執(zhí)行，直至該任務(wù)讓出執(zhí)行權(quán)或者被更高級的任務(wù)搶斷。如果沒有符合條件的任務(wù)需要執(zhí)行，則運行系統(tǒng)中預(yù)留的OSIdleTask（空閑任務(wù)）。

在SmallRTOS系統(tǒng)中，除了相關(guān)參數(shù)采用宏定義進行配置之外，功能模塊也采用宏定義進行配置。其中宏定義OS_SEMAPHORE_ON表示是否啟用信號量（Semaphore，又稱作旗語）功能模塊，若定義為1，則表示啟用信號量（Semaphore，又稱作旗語）功能模塊，若定義為0，則該功能模塊不被啟用；宏定義OS_MSGQ_ON表示是否啟用消息隊列，用法同OS_SEMAPHORE_ON；宏定義OS_MUTEX_ON表示是否啟用互斥信號量，用法同OS_SEMAPHORE_ON；

下面是微型嵌入式實時操作系統(tǒng)SmallRTOS中經(jīng)常用到的接口函數(shù)，供大家使用時參考；

一、系統(tǒng)中任務(wù)相關(guān)的API函數(shù)

OSTaskHandle_t OSTaskCreate(OSTaskFunction_t pxTaskFunction,
void* pvParameter,
const uOS16_t usStackDepth,
uOSBase_t uxPriority,
sOS8_t* pcTaskName);

OSTaskCreate為微型嵌入式實時操作系統(tǒng)SmallRTOS的任務(wù)創(chuàng)建函數(shù)，其中參數(shù)OSTaskFunction_t pxTaskFunction為任務(wù)函數(shù)，該任務(wù)函數(shù)類型定義為void TaskFunction( void *pParameters );任務(wù)函數(shù)中的參數(shù)void *pParameters 亦即OSTaskCreate的第二個參數(shù)；第三個參數(shù)為任務(wù)的?？臻gusStackDepth，?？臻g需要根據(jù)任務(wù)占用的空間多少進行調(diào)整；第四個參數(shù)為任務(wù)的優(yōu)先級，除最低優(yōu)先級0為系統(tǒng)保留外，均可使用。第五個參數(shù)為任務(wù)名字，任務(wù)名字也就是任務(wù)的標簽，主要方便在調(diào)試時區(qū)分不同的任務(wù)。

函數(shù)OSTaskCreate的返回值為OSTaskHandle_t類型的任務(wù)句柄，該句柄可以被其它系統(tǒng)函數(shù)調(diào)用，以設(shè)置或控制任務(wù)的狀態(tài)；
void OSTaskSleep(uOS32_t uxWatiTicks);

OSTaskSleep為微型嵌入式實時操作系統(tǒng)SmallRTOS系統(tǒng)中任務(wù)延遲執(zhí)行設(shè)置函數(shù)，通過此函數(shù)，可以把當前任務(wù)休眠若干毫秒的時間。參數(shù)uOS32_t uxWatiTicks代表休眠的時間長短，單位為Ticks，用戶可以通過OSTICKS_PER_MS把毫秒轉(zhuǎn)換為Ticks計數(shù)；
void OSTaskYield()

OSTaskYield函數(shù)為SmallRTOS中的任務(wù)控制類函數(shù)，在任務(wù)中調(diào)用，用于讓出當前任務(wù)的執(zhí)行權(quán)，并切換到下一個處于eTaskStateReady狀態(tài)的任務(wù)；函數(shù)OSTaskYield并不改變?nèi)蝿?wù)的狀態(tài)，只是把當前正在執(zhí)行的任務(wù)排列到狀態(tài)為eTaskStateReady的任務(wù)隊列的隊尾，若只有當前任務(wù)處于eTaskStateReady狀態(tài)，則仍然執(zhí)行當前任務(wù)；
uOS16_t OSStart( void )

函數(shù)OSStart為OSStartScheduler()函數(shù)的宏定義，OSStartScheduler()函數(shù)是SmallRTOS中的任務(wù)調(diào)度啟動函數(shù)；在該函數(shù)中，系統(tǒng)會設(shè)置空閑任務(wù)OSIdleTask及時鐘中斷；OSIdleTask任務(wù)為系統(tǒng)空閑任務(wù)，若系統(tǒng)當前沒有需要執(zhí)行的任務(wù)，則會調(diào)用該空閑任務(wù)，空閑任務(wù)可以用于統(tǒng)計當前系統(tǒng)的利用率，及釋放處于待刪除狀態(tài)任務(wù)的資源；時鐘中斷則為系統(tǒng)的ticks配置，整個系統(tǒng)的運行即依賴此ticks驅(qū)動運行；

二、任務(wù)同步信號量相關(guān)的API函數(shù)

OSSemHandle_t OSSemCreate()

函數(shù)OSSemCreate為信號量（Semaphore）創(chuàng)建函數(shù)，用于創(chuàng)建任務(wù)間同步操作的信號量。信號量創(chuàng)建后，默認有效信號量計數(shù)值為0，表示該信號量無有效信號，對應(yīng)的OSSemPend函數(shù)處于阻塞狀態(tài)，等待有效信號；其返回值為OSSemHandle_t類型的句柄，方便用于對該信號量的操控；
sOSBase_t OSSemPend( OSSemHandle_t SemHandle, uOSTick_t xTicksToWait)

函數(shù)OSSemPend為信號量等待函數(shù)，在任務(wù)執(zhí)行函數(shù)中調(diào)用，用于等待相關(guān)同步的信號量；參數(shù)OSSemHandle_t SemHandle為信號量句柄，參數(shù)uOSTick_t xTicksToWait為任務(wù)阻塞時間，單位為Tick數(shù)，若設(shè)置為OSPEND_FORVER_VALUE，則會永遠阻塞，直至指定信號量SemHandle獲取到有效信號；
sOSBase_t OSSemPost( OSSemHandle_t SemHandle)

函數(shù)OSSemPost用于向指定信號量發(fā)送有效信號，使處于等待該信號量的任務(wù)獲取同步信號，以便恢復(fù)執(zhí)行。注：此函數(shù)不能在中斷服務(wù)函數(shù)中調(diào)用。
sOSBase_t OSSemPostFromISR( OSSemHandle_t SemHandle )

函數(shù)OSSemPostFromISR用于向指定信號量發(fā)送有效信號，使處于等待該信號量的任務(wù)獲取同步信號，以便恢復(fù)執(zhí)行。注：此函數(shù)只能在中斷服務(wù)函數(shù)中調(diào)用。

三、任務(wù)同步消息相關(guān)的API函數(shù)

OSMsgQHandle_t OSMsgQCreate( const uOSBase_t uxQueueLength, const uOSBase_t uxItemSize)

函數(shù)OSMsgQCreate為消息隊列的創(chuàng)建函數(shù)，用于創(chuàng)建任務(wù)間同步操作的消息隊列，參數(shù)uxQueueLength為消息隊列中的消息數(shù)的容量（消息數(shù)目超過此容量，則發(fā)送任務(wù)掛起，直到消息隊列有空閑位置），第二個參數(shù)uxItemSize為單個消息的長度。其返回值為OSMsgQHandle_t類型的消息隊列句柄，方便對消息隊列的操控；
sOSBase_t OSMsgQReceive( OSMsgQHandle_t MsgQHandle, void * const pvBuffer, uOSTick_t xTicksToWait)

函數(shù)OSMsgQReceive用于在任務(wù)中接收指定消息隊列的消息，在任務(wù)執(zhí)行函數(shù)中調(diào)用；該函數(shù)為任務(wù)阻塞函數(shù)。參數(shù)MsgQHandle為消息隊列句柄, 參數(shù)pvBuffer表示消息的指針，參數(shù)xTicksToWait為消息隊列等待接收時間，單位為Tick，若設(shè)置為OSPEND_FORVER_VALUE，則會永遠等待，直至指定消息隊列MsgQHandle獲取到有效消息為止。函數(shù)返回值代表消息接收狀態(tài)，若為FALSE則未接收到有效消息，若為TRUE則接收到有效消息；
sOSBase_t OSMsgQReceiveFromISR( OSMsgQHandle_t MsgQHandle, void * const pvBuffer)

函數(shù)OSMsgQReceiveFromISR用于在中斷函數(shù)中接收指定消息隊列的消息；參數(shù)MsgQHandle為消息隊列句柄, 參數(shù)pvBuffer表示消息的指針，該函數(shù)不會阻塞。函數(shù)返回值代表消息接收狀態(tài)，若為FALSE則未接收到有效消息，若為TRUE則接收到有效消息；注：此函數(shù)只能在中斷服務(wù)函數(shù)中調(diào)用。
sOSBase_t OSMsgQSend( OSMsgQHandle_t MsgQHandle, const void * const pvItemToQueue, uOSTick_t xTicksToWait)

函數(shù)OSMsgQSend用于向指定的消息隊列發(fā)送消息，使處于等待該消息的任務(wù)獲取同步消息，并恢復(fù)執(zhí)行，其中參數(shù)MsgQHandle表示消息隊列，參數(shù)pvItemToQueue表示消息地址（指針），參數(shù)xTicksToWait為消息發(fā)送等待接收時間，單位為Tick，若設(shè)置為OSPEND_FORVER_VALUE，則會永遠等待，直至指定消息隊列MsgQHandle有空閑位置。函數(shù)返回值代表消息發(fā)送狀態(tài)，若為FALSE則消息發(fā)送失敗，若為TRUE則消息發(fā)送成功；注：此函數(shù)不能在中斷服務(wù)函數(shù)中調(diào)用。
sOSBase_t OSMsgQSendFromISR( OSMsgQHandle_t MsgQHandle, const void * const pvItemToQueue)

函數(shù)OSMsgQSendFromISR用于向指定的消息隊列發(fā)送消息，使處于等待該消息的任務(wù)獲取同步消息，并恢復(fù)執(zhí)行，其中參數(shù)MsgQHandle表示消息隊列，參數(shù)pvItemToQueue表示消息地址（指針），如果消息隊列已滿，則函數(shù)不會阻塞，直接返回發(fā)送失敗信息。注：此函數(shù)只能在中斷服務(wù)函數(shù)中調(diào)用。

四、定時器相關(guān)的API函數(shù)

OSTimerHandle_t OSTimerCreate(OSTimerFunction_t Function, void* pvParameter, uOSBase_t uxPeriodicTimeMS, sOS8_t* pcName)

接口函數(shù)OSTimerCreate用于創(chuàng)建定時器。其中參數(shù)Function為定時器的服務(wù)函數(shù)，用于響應(yīng)定時器，函數(shù)OSTimerFunction_t的定義類型為void TimerFunction(void *pParameters )。pvParameter為定時器服務(wù)函數(shù)的參數(shù)，不用時可以設(shè)置為NULL。參數(shù)uxPeriodicTimeMS為定時器的周期，單位為毫秒。參數(shù)pcName為定時器的名稱，方便區(qū)分不同的定時器；注意：定時器服務(wù)函數(shù)中禁止添加信號量等待、消息隊列等待等用于阻塞的函數(shù)，為不影響整個系統(tǒng)的性能，定時器服務(wù)函數(shù)耗時越少越好。
uOSBase_t OSTimerStart(OSTimerHandle_t const TimerHandle)

定時器創(chuàng)建完畢后并不會自動啟動，需要用戶顯示的調(diào)用啟動函數(shù)OSTimerStart()，之后定時器才會生效。參數(shù)TimerHandle為定時器句柄，為定時器創(chuàng)建函數(shù)OSTimerCreate()的返回值；
uOSBase_t OSTimerStop(OSTimerHandle_t const TimerHandle)

定時啟動后，用戶可以通過接口函數(shù)OSTimerStop()停止定時。參數(shù)TimerHandle為定時器句柄，為定時器創(chuàng)建函數(shù)OSTimerCreate()的返回值；

簡單示例程序

下面是采用實時嵌入式操作系統(tǒng)SmallRTOS實現(xiàn)的多任務(wù)處理演示示例，主要包括任務(wù)創(chuàng)建、信號量創(chuàng)建、任務(wù)延時等功能。代碼如下：
OSTaskHandle_t HWTaskHandle = NULL;
OSTaskHandle_t GBTaskHandle = NULL;
OSSemHandle_t GBSemaphoreHandle = NULL;

void TaskHelloWorld( void *pvParameters );
void TaskGoodBye( void *pvParameters );

int main( void )
{
GBSemaphoreHandle = OSSemCreate();

// configure and start tasks
HWTaskHandle = OSTaskCreate(TaskHelloWorld, NULL, OSMINIMAL_STACK_SIZE, OSLOWEAST_PRIORITY+1, "HW");
GBTaskHandle = OSTaskCreate(TaskGoodBye, NULL, OSMINIMAL_STACK_SIZE, OSLOWEAST_PRIORITY+2, "GB");

/* Start the tasks and timer running. */
OSStart();
for( ;; );
return 0;
}

void TaskHelloWorld( void *pvParameters )
{
/* Remove compiler warning about unused parameter. */
( void ) pvParameters;
for( ;; )
{
OSSemPost(GBSemaphoreHandle);
OSTaskSleep(200*OSTICKS_PER_MS);
}
}

void TaskGoodBye( void *pvParameters )
{
/* Remove compiler warning about unused parameter. */
( void ) pvParameters;
for( ;; )
{
OSSemPend(GBSemaphoreHandle, OSPEND_FOREVER_VALUE);
}
}