uC/OS-II 常用函數(shù)參考手冊

 任務(wù)管理

1 OSTaskCreate()

建立一個新任務(wù)。任務(wù)的建立可以在多任務(wù)環(huán)境啟動之前，也可以在正在運行的任務(wù)中建立。中斷處理程序中不能建立任務(wù)。一個任務(wù)可以為無限循環(huán)的結(jié)構(gòu)。

函數(shù)原型：INT8U OSTaskCreate(void (*task)(void *pd), void *pdata, OS_STK *ptos, INT8U prio);

參數(shù)說明：task 是指向任務(wù)代碼首地址的指針。

pdata 指向一個數(shù)據(jù)結(jié)構(gòu)，該結(jié)構(gòu)用來在建立任務(wù)時向任務(wù)傳遞參數(shù)。

ptos is a pointer to the task's top of stack. If the configuration constant OS_STK_GROWTH is set to 1, the stack is assumed to grow downward (i.e. from high memory to low memory). 'pstk' will thus point to the highest (valid) memory location of the stack. If OS_STK_GROWTH is set to 0, 'pstk' will point to the lowest memory location of the stack and the stack will grow with increasing memory locations.

prio is the task's priority. A unique priority MUST be assigned to each task and the lower the number, the higher the priority.

返回值：

OSTaskCreate() 的返回值為下述之一：

* OS_NO_ERR：函數(shù)調(diào)用成功。

* OS_PRIO_EXIST：具有該優(yōu)先級的任務(wù)已經(jīng)存在。

* OS_PRIO_INVALID：參數(shù)指定的優(yōu)先級大于OS_LOWEST_PRIO。

* OS_NO_MORE_TCB：系統(tǒng)中沒有OS_TCB可以分配給任務(wù)了。

2 OSTaskSuspend()

無條件掛起一個任務(wù)。調(diào)用此函數(shù)的任務(wù)也可以傳遞參數(shù) OS_PRIO_SELF，掛起調(diào)用任務(wù)本身。當(dāng)前任務(wù)掛起后，只有其他任務(wù)才能喚醒被掛起的任務(wù)。任務(wù)掛起后，系統(tǒng)會重新進行任務(wù)調(diào)度，運行下一個優(yōu)先級最高的就緒任務(wù)。喚醒掛起任務(wù)需要調(diào)用函數(shù)OSTaskResume()。

任務(wù)的掛起是可以疊加到其他操作上的。例如，任務(wù)被掛起時正在進行延時操作，那么任務(wù)的喚醒就需要兩個條件：延時的結(jié)束以及其他任務(wù)的喚醒操作。又如，任務(wù)被掛起時正在等待信號量，當(dāng)任務(wù)從信號量的等待對列中清除后也不能立即運行，而必須等到被喚醒后。

函數(shù)原型：INT8U OSTaskSuspend(INT8U prio);

參數(shù)說明：prio為指定要獲取掛起的任務(wù)優(yōu)先級，也可以指定參數(shù) OS_PRIO_SELF，掛起任務(wù)本身。此時，下一個優(yōu)先級最高的就緒任務(wù)將運行。

返回值：

OSTaskSuspend() 的返回值為下述之一：

* OS_NO_ERR：函數(shù)調(diào)用成功。

* OS_TASK_SUSPEND_IDLE：試圖掛起μC/OS-II中的空閑任務(wù)(Idle task)。此為非法操作。

* OS_PRIO_INVALID：參數(shù)指定的優(yōu)先級大于 OS_LOWEST_PRIO 或沒有設(shè)定 OS_PRIO_SELF 的值。

* OS_TASK_SUSPEND_PRIO：要掛起的任務(wù)不存在。

3 OSTaskResume()

喚醒一個用 OSTaskSuspend() 函數(shù)掛起的任務(wù)。OSTaskResume() 也是唯一能“解掛”掛起任務(wù)的函數(shù)。

函數(shù)原型：INT8U OSTaskResume(INT8U prio);

參數(shù)說明：prio指定要喚醒任務(wù)的優(yōu)先級。

返回值：

OSTaskResume() 的返回值為下述之一：

* OS_NO_ERR：函數(shù)調(diào)用成功。

* OS_TASK_RESUME_PRIO：要喚醒的任務(wù)不存在。

* OS_TASK_NOT_SUSPENDED：要喚醒的任務(wù)不在掛起狀態(tài)。

* OS_PRIO_INVALID：參數(shù)指定的優(yōu)先級大于或等于OS_LOWEST_PRIO。

信號量

1 OSSemCreate()

該函數(shù)建立并初始化一個信號量，信號量的作用如下：

* 允許一個任務(wù)和其他任務(wù)或者中斷同步

* 取得設(shè)備的使用權(quán)

* 標(biāo)志事件的發(fā)生

函數(shù)原型：OS_EVENT *OSSemCreate(INT16U value);

參數(shù)說明：value 參數(shù)是所建立的信號量的初始值，可以取0到65535之間的任何值。

返回值：

OSSemCreate() 函數(shù)返回指向分配給所建立的信號量的控制塊的指針。如果沒有可用的控制塊，OSSemCreate() 函數(shù)返回空指針。

2 OSSemPend()

該函數(shù)用于任務(wù)試圖取得設(shè)備的使用權(quán)、任務(wù)需要和其他任務(wù)或中斷同步、任務(wù)需要等待特定事件的發(fā)生的場合。如果任務(wù)調(diào)用OSSemPend() 函數(shù)時，信號量的值大于零，OSSemPend() 函數(shù)遞減該值并返回該值。如果調(diào)用時信號量值等于零，OSSemPend() 函數(shù)將任務(wù)加入該信號量的等待隊列。OSSemPend() 函數(shù)掛起當(dāng)前任務(wù)直到其他的任務(wù)或中斷設(shè)置信號量或超出等待的預(yù)期時間。如果在預(yù)期的時鐘節(jié)拍內(nèi)信號量被設(shè)置，μC/OS-Ⅱ默認讓最高優(yōu)先級的任務(wù)取得信號量并回到就緒狀態(tài)。一個被OSTaskSuspend() 函數(shù)掛起的任務(wù)也可以接受信號量，但這個任務(wù)將一直保持掛起狀態(tài)直到通過調(diào)用OSTaskResume() 函數(shù)恢復(fù)該任務(wù)的運行。

函數(shù)原型：void OSSemPend ( OS_EVNNT *pevent, INT16U timeout, int8u *err );

參數(shù)說明：pevent 是指向信號量的指針。該指針的值在建立該信號量時可以得到。(參考OSSemCreate() 函數(shù))。

timeout 允許一個任務(wù)在經(jīng)過了指定數(shù)目的時鐘節(jié)拍后還沒有得到需要的信號量時恢復(fù)就緒狀態(tài)。如果該值為零表示任務(wù)將持續(xù)地等待信號量，最大的等待時間為65535個時鐘節(jié)拍。這個時間長度并不是非常嚴格的，可能存在一個時鐘節(jié)拍的誤差。

err 是指向包含錯誤碼的變量的指針，返回的錯誤碼可能為下述幾種：

* OS_NO_ERR ：信號量不為零。

* OS_TIMEOUT ：信號量沒有在指定數(shù)目的時鐘周期內(nèi)被設(shè)置。

* OS_ERR_PEND_ISR ：從中斷調(diào)用該函數(shù)。雖然規(guī)定了不允許從中斷調(diào)用該函數(shù)，但μC/OS-Ⅱ仍然包含了檢測這種情況的功能。

* OS_ERR_EVENT_TYPE ：pevent 不是指向信號量的指針。

返回值：無

3 OSSemPost()

該函數(shù)用于設(shè)置指定的信號量。如果指定的信號量是零或大于零，OSSemPost() 函數(shù)遞增該信號量的值并返回。如果有任何任務(wù)在等待該信號量，則最高優(yōu)先級的任務(wù)將得到信號量并進入就緒狀態(tài)。任務(wù)調(diào)度函數(shù)將進行任務(wù)調(diào)度，決定當(dāng)前運行的任務(wù)是否仍然為最高優(yōu)先級的就緒任務(wù)。

函數(shù)原型：INT8U OSSemPost(OS_EVENT *pevent);

參數(shù)說明：pevent 是指向信號量的指針。該指針的值在建立該信號量時可以得到。(參考OSSemCreate() 函數(shù))。

返回值：

OSSemPost() 函數(shù)的返回值為下述之一：

* OS_NO_ERR ：信號量被成功地設(shè)置

* OS_SEM_OVF ：信號量的值溢出

* OS_ERR_EVENT_TYPE ：pevent 不是指向信號量的指針

時間

1 OSTimeDly()

該函數(shù)用于將一個任務(wù)延時若干個時鐘節(jié)拍。如果延時時間大于0，系統(tǒng)將立即進行任務(wù)調(diào)度。延時時間的長度可從0到65535個時鐘節(jié)拍。延時時間0表示不進行延時，函數(shù)將立即返回調(diào)用者。延時的具體時間依賴于系統(tǒng)每秒鐘有多少個時鐘節(jié)拍(由文件OS_CFG.H中的OS_TICKS_PER_SEC宏來設(shè)定)。

函數(shù)原型：void OSTimeDly (INT16U ticks);

參數(shù)說明：ticks 為要延時的時鐘節(jié)拍數(shù)。

返回值：無

2 OSTimeDlyHMSM()

該函數(shù)用于將一個任務(wù)延時若干時間。延時的單位是小時、分、秒、毫秒。調(diào)用 OSTimeDlyHMSM() 后，如果延時時間不為0，系統(tǒng)將立即進行任務(wù)調(diào)度。

函數(shù)原型: INT8U OSTimeDlyHMSM (INT8U hours，INT8U minutes，INT8U seconds，INT16U milli);

參數(shù)說明：hours 為延時小時數(shù)，范圍從0-255。

minutes 為延時分鐘數(shù)，范圍從0-59。

seconds 為延時秒數(shù)，范圍從0-59

milli 為延時毫秒數(shù)，范圍從0-999。

需要說明的是，操作系統(tǒng)在處理延時操作時都是以時鐘節(jié)拍為單位的，實際的延時時間是時鐘節(jié)拍的整數(shù)倍。如果系統(tǒng)時鐘節(jié)拍的間隔是10ms，而設(shè)定延時為5ms的話，則不會產(chǎn)生延時操作;而如果設(shè)定延時為15ms，則實際的延時是兩個時鐘節(jié)拍，也就是20ms。

返回值：

OSTimeDlyHMSM() 的返回值為下述之一：

* OS_NO_ERR：函數(shù)調(diào)用成功。

* OS_TIME_INVALID_MINUTES：參數(shù)錯誤，分鐘數(shù)大于59。

* OS_TIME_INVALID_SECONDS：參數(shù)錯誤，秒數(shù)大于59。

* OS_TIME_INVALID_MILLI：參數(shù)錯誤，毫秒數(shù)大于999。

* OS_TIME_ZERO_DLY：四個參數(shù)全為0。

內(nèi)存管理

1 OSMemCreate()

該函數(shù)建立并初始化一個用于動態(tài)內(nèi)存分配的區(qū)域，該內(nèi)存區(qū)域包含指定數(shù)目的、大小確定的內(nèi)存塊。應(yīng)用可以動態(tài)申請這些內(nèi)存塊并在用完后將其釋放回這個內(nèi)存區(qū)域。該函數(shù)的返回值就是指向這個內(nèi)存區(qū)域控制塊的指針，并作為OSMemGet()，OSMemPut()，OSMemQuery() 等相關(guān)調(diào)用的參數(shù)。

函數(shù)原型：OS_MEM *OSMemCreate( void *addr, INT32U nblks, INT32U blksize, INT8U *err );

參數(shù)說明：addr 建立的內(nèi)存區(qū)域的起始地址。可以使用靜態(tài)數(shù)組或在系統(tǒng)初始化時使用 malloc() 函數(shù)來分配這個區(qū)域的空間。

nblks 內(nèi)存塊的數(shù)目。每一個內(nèi)存區(qū)域最少需要定義兩個內(nèi)存塊。

blksize 每個內(nèi)存塊的大小，最小應(yīng)該能夠容納一個指針變量。

err 是指向包含錯誤碼的變量的指針。Err可能是如下幾種情況：

* OS_NO_ERR ：成功建立內(nèi)存區(qū)域。

* OS_MEM_INVALID_ADDR ：非法地址，即地址為空指針。

* OS_MEM_INVALID_PART ：沒有空閑的內(nèi)存區(qū)域。

* OS_MEM_INVALID_BLKS ：沒有為內(nèi)存區(qū)域建立至少兩個內(nèi)存塊。

* OS_MEM_INVALID_SIZE ：內(nèi)存塊大小不足以容納一個指針變量。

返回值：

OSMemCreate() 函數(shù)返回指向所創(chuàng)建的內(nèi)存區(qū)域控制塊的指針。如果創(chuàng)建失敗，函數(shù)返回空指針。

2 OSMemGet()

該函數(shù)用于從內(nèi)存區(qū)域分配一個內(nèi)存塊。用戶程序必須知道所建立的內(nèi)存塊的大小，并必須在使用完內(nèi)存塊后釋放它?？梢远啻握{(diào)用 OSMemGet() 函數(shù)。它的返回值就是指向所分配內(nèi)存塊的指針，并作為 OSMemPut() 函數(shù)的參數(shù)。

函數(shù)原型：void *OSMemGet(OS_MEM *pmem, INT8U *err);

參數(shù)說明：pmem 是指向內(nèi)存區(qū)域控制塊的指針，可以從 OSMemCreate() 函數(shù)的返回值中得到。

err 是指向包含錯誤碼的變量的指針。Err可能是如下情況：

* OS_NO_ERR ：成功得到一個內(nèi)存塊。

* OS_MEM_NO_FREE_BLKS ：內(nèi)存區(qū)域中已經(jīng)沒有足夠的內(nèi)存塊。

返回值：

OSMemGet() 函數(shù)返回指向所分配內(nèi)存塊的指針。如果沒有可分配的內(nèi)存塊，OSMemGet() 函數(shù)返回空指針。

3 OSMemPut()

該函數(shù)用于釋放一個內(nèi)存塊，內(nèi)存塊必須釋放回它原先所在的內(nèi)存區(qū)域，否則會造成系統(tǒng)錯誤。

函數(shù)原型：INT8U OSMemPut (OS_MEM *pmem, void *pblk);

參數(shù)說明：pmem 是指向內(nèi)存區(qū)域控制塊的指針，可以從 OSMemCreate() 函數(shù)的返回值中得到。

pblk 是指向?qū)⒈会尫诺膬?nèi)存塊的指針。

返回值：

OSMemPut() 函數(shù)的返回值為下述之一：

* OS_NO_ERR ：成功釋放內(nèi)存塊

* OS_MEM_FULL ：內(nèi)存區(qū)域已滿，不能再接受更多釋放的內(nèi)存塊。這種情況說明用戶程序出現(xiàn)了錯誤，釋放了多于用 OSMemGet() 函數(shù)得到的內(nèi)存塊。

4 OSMemQuery()

該函數(shù)用于得到內(nèi)存區(qū)域的信息。

函數(shù)原型：INT8U OSMemQuery(OS_MEM *pmem, OS_MEM_DATA *pdata);

參數(shù)說明：pmem 是指向內(nèi)存區(qū)域控制塊的指針，可以從 OSMemCreate() 函數(shù)的返回值中得到。

pdata 是一個指向 OS_MEM_DATA 數(shù)據(jù)結(jié)構(gòu)的指針，該數(shù)據(jù)結(jié)構(gòu)包含了以下的域：

void OSAddr; /* 指向內(nèi)存區(qū)域起始地址的指針 */

void OSFreeList; /* 指向空閑內(nèi)存塊列表起始地址的指針 */

INT32U OSBlkSize; /* 每個內(nèi)存塊的大小 */

INT32U OSNBlks; /* 該內(nèi)存區(qū)域中的內(nèi)存塊總數(shù) */

INT32U OSNFree; /* 空閑的內(nèi)存塊數(shù)目 */

INT32U OSNUsed; /* 已使用的內(nèi)存塊數(shù)目 */

消息隊列

1 OSQCreate()

該函數(shù)用于建立一個消息隊列。任務(wù)或中斷可以通過消息隊列向一個或多個任務(wù)發(fā)送消息。消息的含義是和具體的應(yīng)用密切相關(guān)的。

函數(shù)原型：OS_EVENT *OSQCreate (void **start, INT8U size);

參數(shù)說明：start 是消息內(nèi)存區(qū)的首地址，消息內(nèi)存區(qū)是一個指針數(shù)組。

size 是消息內(nèi)存區(qū)的大小。

返回值：

OSQCreate() 函數(shù)返回一個指向消息隊列控制塊的指針。如果沒有空閑的控制塊，OSQCreate() 函數(shù)返回空指針。

2 OSQPend()

該函數(shù)用于任務(wù)等待消息。消息通過中斷或任務(wù)發(fā)送給需要的任務(wù)。消息是一個指針變量，在不同的應(yīng)用中消息的具體含義不同。如果調(diào)用 OSQPend() 函數(shù)時隊列中已經(jīng)存在消息，那么該消息被返回給 OSQPend() 函數(shù)的調(diào)用者，該消息同時從隊列中清除。如果調(diào)用 OSQPend() 函數(shù)時隊列中沒有消息，OSQPend() 函數(shù)掛起調(diào)用任務(wù)直到得到消息或超出定義的超時時間。如果同時有多個任務(wù)等待同一個消息，μC/OS-Ⅱ默認最高優(yōu)先級的任務(wù)取得消息。一個由 OSTaskSuspend() 函數(shù)掛起的任務(wù)也可以接受消息，但這個任務(wù)將一直保持掛起狀態(tài)直到通過調(diào)用 OSTaskResume() 函數(shù)恢復(fù)任務(wù)的運行。

函數(shù)原型：void *OSQPend (OS_EVENT *pevent, INT16U timeout, INT8U *err);

參數(shù)說明：pevent 是指向消息隊列的指針，該指針的值在建立該隊列時可以得到。(參考 OSQCreate() 函數(shù))。

timeout 允許一個任務(wù)以指定數(shù)目的時鐘節(jié)拍等待消息。超時后如果還沒有得到消息則恢復(fù)成就緒狀態(tài)。如果該值設(shè)置成零則表示任務(wù)將持續(xù)地等待消息，最大的等待時間為65535個時鐘節(jié)拍。這個時間長度并不是非常嚴格的，可能存在一個時鐘節(jié)拍的誤差。

err 是指向包含錯誤碼的變量的指針。OSQPend() 函數(shù)返回的錯誤碼可能為下述幾種：

* OS_NO_ERR ：消息被正確地接受。

* OS_TIMEOUT ：消息沒有在指定的時鐘周期數(shù)內(nèi)接收到消息。

* OS_ERR_PEND_ISR ：從中斷調(diào)用該函數(shù)。雖然規(guī)定了不允許從中斷中調(diào)用該函數(shù)，但μC/OS-Ⅱ仍然包含了檢測這種情況的功能。

* OS_ERR_EVENT_TYPE ：pevent 不是指向消息隊列的指針。

返回值：

OSQPend() 函數(shù)返回取得的消息并將 *err 置為 OS_NO_ERR。如果沒有在指定數(shù)目的時鐘節(jié)拍內(nèi)接受到消息，OSQPend() 函數(shù)返回空指針并將 *err 設(shè)置為 OS_TIMEOUT。

3 OSQPostFront()

該函數(shù)用于向消息隊列發(fā)送消息。OSQPostFront() 函數(shù)和 OSQPost() 函數(shù)非常相似，不同之處在于 OSQPostFront() 函數(shù)將發(fā)送的消息插到消息隊列的最前端。也就是說，OSQPostFront() 函數(shù)使得消息隊列按照后入先出(LIFO)的方式工作，而不是先入先出(FIFO)。消息是一個指針長度的變量，在不同的應(yīng)用中消息的含義也可能不同。如果隊列中已經(jīng)存滿消息，則此調(diào)用將返回錯誤碼。OSQPost() 函數(shù)也是如此。在調(diào)用此函數(shù)時如果有任何任務(wù)在等待隊列中的消息，則最高優(yōu)先級的任務(wù)將得到這個消息。如果等待消息的任務(wù)優(yōu)先級比發(fā)送消息的任務(wù)優(yōu)先級高，那么高優(yōu)先級的任務(wù)在得到消息后將立即搶占當(dāng)前任務(wù)執(zhí)行，也就是說，將發(fā)生一次任務(wù)切換。

函數(shù)原型：INT8U OSQPostFront(OS_EVENT *pevent, void *msg);

參數(shù)說明：pevent 是指向即將接收消息的消息隊列的指針。該指針的值在建立隊列時可以得到。(參考 OSQCreate() 函數(shù))。

msg 是即將發(fā)送的消息的指針。不允許傳遞一個空指針。

返回值：

OSQPostFront() 函數(shù)的返回值為下述之一：

* OS_NO_ERR ：消息成功地放到消息隊列中。

* OS_Q_FULL ：消息隊列已滿。

* OS_ERR_EVENT_TYPE ：pevent 不是指向消息隊列的指針。

4 OSQPost()

該函數(shù)用于向消息隊列發(fā)送消息。消息是一個指針長度的變量，在不同的應(yīng)用中消息的含義也可能不同。如果隊列中已經(jīng)存滿消息，則此調(diào)用返回錯誤碼。如果有任何任務(wù)在等待隊列中的消息，則最高優(yōu)先級的任務(wù)將得到這個消息。如果等待消息的任務(wù)優(yōu)先級比發(fā)送消息的任務(wù)優(yōu)先級高，那么高優(yōu)先級的任務(wù)將在得到消息后立即搶占當(dāng)前任務(wù)執(zhí)行，也就是說，將發(fā)生一次任務(wù)切換。消息是以先入先出(FIFO)方式進入隊列的，即先進入隊列的消息先被傳遞給任務(wù)。

函數(shù)原型：INT8U OSQPost(OS_EVENT *pevent, void *msg);

參數(shù)說明：pevent 是指向即將接受消息的消息隊列的指針。該指針的值在建立隊列時可以得到。(參考 OSQCreate() 函數(shù))。

msg 是即將發(fā)送給隊列的消息。不允許傳遞一個空指針。

返回值：

OSQPost() 函數(shù)的返回值為下述之一：

* OS_NO_ERR ：消息成功地放到消息隊列中。

* OS_Q_FULL ：消息隊列已滿。

* OS_ERR_EVENT_TYPE ：pevent 不是指向消息隊列的指針。

5 OSQFlush()

該函數(shù)用于清空消息隊列。

函數(shù)原型：INT8U *OSQFlush(OS_EVENT *pevent);

參數(shù)說明：pevent 是指向消息隊列的指針。該指針的值在建立隊列時可以得到。(參考 OSQCreate() 函數(shù))。

返回值：

OSQFlush() 函數(shù)的返回值為下述之一：

* OS_NO_ERR ：消息隊列被成功清空

* OS_ERR_EVENT_TYPE ：試圖清除不是消息隊列的對象

6 OSQQuery()

該函數(shù)用來取得消息隊列的信息。用戶程序必須建立一個 OS_Q_DATA 的數(shù)據(jù)結(jié)構(gòu)，該結(jié)構(gòu)用來保存從消息隊列的控制塊得到的數(shù)據(jù)。通過調(diào)用該函數(shù)可以知道是否有任務(wù)在等待消息、有多少個任務(wù)在等待消息、隊列中有多少消息以及消息隊列可以容納的消息數(shù)。OSQQuery() 函數(shù)還可以得到即將被傳遞給任務(wù)的消息。

函數(shù)原型：INT8U OSQQuery(OS_EVENT *pevent, OS_Q_DATA *pdata);

參數(shù)說明：pevent 是指向消息隊列的指針。該指針的值在建立消息隊列時可以得到。(參考 OSQCreate() 函數(shù))。

pdata 是指向 OS_Q_DATA 數(shù)據(jù)結(jié)構(gòu)的指針，該數(shù)據(jù)結(jié)構(gòu)包含下述成員：

void *OSMsg; /* 下一個可用的消息 */

INT16U OSNMsgs; /* 隊列中的消息數(shù)目 */

INT16U OSQSize; /* 消息隊列的大小 */

INT8U OSEventTbl[OS_EVENT_TBL_SIZE]; /* 消息隊列的等待隊列 */

INT8U OSEventGrp;

返回值：

OSQQuery() 函數(shù)的返回值為下述之一：

* OS_NO_ERR ：調(diào)用成功

* OS_ERR_EVENT_TYPE ：pevent 不是指向消息隊列的指針。

7 OSQDel()

該函數(shù)用于刪除指定的消息隊列。