uC/OS-II 常用函數(shù)參考手冊
任務管理
1 OSTaskCreate()
建立一個新任務。任務的建立可以在多任務環(huán)境啟動之前，也可以在正在運行的任務中建立。中斷處理程序中不能建立任務。一個任務可以為無限循環(huán)的結構。
函數(shù)原型：INT8U OSTaskCreate(void (*task)(void *pd), void *pdata, OS_STK *ptos, INT8U prio);
參數(shù)說明：task 是指向任務代碼首地址的指針。
pdata 指向一個數(shù)據(jù)結構，該結構用來在建立任務時向任務傳遞參數(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)先級的任務已經(jīng)存在。
* OS_PRIO_INVALID：參數(shù)指定的優(yōu)先級大于OS_LOWEST_PRIO。
* OS_NO_MORE_TCB：系統(tǒng)中沒有OS_TCB可以分配給任務了。
2 OSTaskSuspend()
無條件掛起一個任務。調(diào)用此函數(shù)的任務也可以傳遞參數(shù) OS_PRIO_SELF，掛起調(diào)用任務本身。當前任務掛起后，只有其他任務才能喚醒被掛起的任務。任務掛起后，系統(tǒng)會重新進行任務調(diào)度，運行下一個優(yōu)先級最高的就緒任務。喚醒掛起任務需要調(diào)用函數(shù)OSTaskResume()。
任務的掛起是可以疊加到其他操作上的。例如，任務被掛起時正在進行延時操作，那么任務的喚醒就需要兩個條件：延時的結束以及其他任務的喚醒操作。又如，任務被掛起時正在等待信號量，當任務從信號量的等待對列中清除后也不能立即運行，而必須等到被喚醒后。
函數(shù)原型：INT8U OSTaskSuspend(INT8U prio);
參數(shù)說明：prio為指定要獲取掛起的任務優(yōu)先級，也可以指定參數(shù) OS_PRIO_SELF，掛起任務本身。此時，下一個優(yōu)先級最高的就緒任務將運行。
返回值：
OSTaskSuspend() 的返回值為下述之一：
* OS_NO_ERR：函數(shù)調(diào)用成功。
* OS_TASK_SUSPEND_IDLE：試圖掛起μC/OS-II中的空閑任務(Idle task)。此為非法操作。
* OS_PRIO_INVALID：參數(shù)指定的優(yōu)先級大于 OS_LOWEST_PRIO 或沒有設定 OS_PRIO_SELF 的值。
* OS_TASK_SUSPEND_PRIO：要掛起的任務不存在。
3 OSTaskResume()
喚醒一個用 OSTaskSuspend() 函數(shù)掛起的任務。OSTaskResume() 也是唯一能“解掛”掛起任務的函數(shù)。
函數(shù)原型：INT8U OSTaskResume(INT8U prio);
參數(shù)說明：prio指定要喚醒任務的優(yōu)先級。
返回值：
OSTaskResume() 的返回值為下述之一：
* OS_NO_ERR：函數(shù)調(diào)用成功。
* OS_TASK_RESUME_PRIO：要喚醒的任務不存在。
* OS_TASK_NOT_SUSPENDED：要喚醒的任務不在掛起狀態(tài)。
* OS_PRIO_INVALID：參數(shù)指定的優(yōu)先級大于或等于OS_LOWEST_PRIO。
信號量
1 OSSemCreate()
該函數(shù)建立并初始化一個信號量，信號量的作用如下：
* 允許一個任務和其他任務或者中斷同步
* 取得設備的使用權
* 標志事件的發(fā)生
函數(shù)原型：OS_EVENT *OSSemCreate(INT16U value);
參數(shù)說明：value 參數(shù)是所建立的信號量的初始值，可以取0到65535之間的任何值。
返回值：
OSSemCreate() 函數(shù)返回指向分配給所建立的信號量的控制塊的指針。如果沒有可用的控制塊，OSSemCreate() 函數(shù)返回空指針。
2 OSSemPend()
該函數(shù)用于任務試圖取得設備的使用權、任務需要和其他任務或中斷同步、任務需要等待特定事件的發(fā)生的場合。如果任務調(diào)用OSSemPend() 函數(shù)時，信號量的值大于零，OSSemPend() 函數(shù)遞減該值并返回該值。如果調(diào)用時信號量值等于零，OSSemPend() 函數(shù)將任務加入該信號量的等待隊列。OSSemPend() 函數(shù)掛起當前任務直到其他的任務或中斷設置信號量或超出等待的預期時間。如果在預期的時鐘節(jié)拍內(nèi)信號量被設置，μC/OS-Ⅱ默認讓最高優(yōu)先級的任務取得信號量并回到就緒狀態(tài)。一個被OSTaskSuspend() 函數(shù)掛起的任務也可以接受信號量，但這個任務將一直保持掛起狀態(tài)直到通過調(diào)用OSTaskResume() 函數(shù)恢復該任務的運行。
函數(shù)原型：void OSSemPend ( OS_EVNNT *pevent, INT16U timeout, int8u *err );
參數(shù)說明：pevent 是指向信號量的指針。該指針的值在建立該信號量時可以得到。(參考OSSemCreate() 函數(shù))。
timeout 允許一個任務在經(jīng)過了指定數(shù)目的時鐘節(jié)拍后還沒有得到需要的信號量時恢復就緒狀態(tài)。如果該值為零表示任務將持續(xù)地等待信號量，最大的等待時間為65535個時鐘節(jié)拍。這個時間長度并不是非常嚴格的，可能存在一個時鐘節(jié)拍的誤差。
err 是指向包含錯誤碼的變量的指針，返回的錯誤碼可能為下述幾種：
* 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 不是指向信號量的指針。
返回值：無
3 OSSemPost()
該函數(shù)用于設置指定的信號量。如果指定的信號量是零或大于零，OSSemPost() 函數(shù)遞增該信號量的值并返回。如果有任何任務在等待該信號量，則最高優(yōu)先級的任務將得到信號量并進入就緒狀態(tài)。任務調(diào)度函數(shù)將進行任務調(diào)度，決定當前運行的任務是否仍然為最高優(yōu)先級的就緒任務。
函數(shù)原型：INT8U OSSemPost(OS_EVENT *pevent);
參數(shù)說明：pevent 是指向信號量的指針。該指針的值在建立該信號量時可以得到。(參考OSSemCreate() 函數(shù))。
返回值：
OSSemPost() 函數(shù)的返回值為下述之一：
* OS_NO_ERR ：信號量被成功地設置
* OS_SEM_OVF ：信號量的值溢出
* OS_ERR_EVENT_TYPE ：pevent 不是指向信號量的指針
時間
1 OSTimeDly()
該函數(shù)用于將一個任務延時若干個時鐘節(jié)拍。如果延時時間大于0，系統(tǒng)將立即進行任務調(diào)度。延時時間的長度可從0到65535個時鐘節(jié)拍。延時時間0表示不進行延時，函數(shù)將立即返回調(diào)用者。延時的具體時間依賴于系統(tǒng)每秒鐘有多少個時鐘節(jié)拍(由文件OS_CFG.H中的OS_TICKS_PER_SEC宏來設定)。
函數(shù)原型：void OSTimeDly (INT16U ticks);
參數(shù)說明：ticks 為要延時的時鐘節(jié)拍數(shù)。
返回值：無
2 OSTimeDlyHMSM()
該函數(shù)用于將一個任務延時若干時間。延時的單位是小時、分、秒、毫秒。調(diào)用 OSTimeDlyHMSM() 后，如果延時時間不為0，系統(tǒng)將立即進行任務調(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，而設定延時為5ms的話，則不會產(chǎn)生延時操作;而如果設定延時為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)存塊。應用可以動態(tài)申請這些內(nèi)存塊并在用完后將其釋放回這個內(nèi)存區(qū)域。該函數(shù)的返回值就是指向這個內(nèi)存區(qū)域控制塊的指針，并作為OSMemGet()，OSMemPut()，OSMemQuery() 等相關調(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)存塊的大小，最小應該能夠容納一個指針變量。
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 是指向將被釋放的內(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ù)結構的指針，該數(shù)據(jù)結構包含了以下的域：
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ù)用于建立一個消息隊列。任務或中斷可以通過消息隊列向一個或多個任務發(fā)送消息。消息的含義是和具體的應用密切相關的。
函數(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ù)用于任務等待消息。消息通過中斷或任務發(fā)送給需要的任務。消息是一個指針變量，在不同的應用中消息的具體含義不同。如果調(diào)用 OSQPend() 函數(shù)時隊列中已經(jīng)存在消息，那么該消息被返回給 OSQPend() 函數(shù)的調(diào)用者，該消息同時從隊列中清除。如果調(diào)用 OSQPend() 函數(shù)時隊列中沒有消息，OSQPend() 函數(shù)掛起調(diào)用任務直到得到消息或超出定義的超時時間。如果同時有多個任務等待同一個消息，μC/OS-Ⅱ默認最高優(yōu)先級的任務取得消息。一個由 OSTaskSuspend() 函數(shù)掛起的任務也可以接受消息，但這個任務將一直保持掛起狀態(tài)直到通過調(diào)用 OSTaskResume() 函數(shù)恢復任務的運行。
函數(shù)原型：void *OSQPend (OS_EVENT *pevent, INT16U timeout, INT8U *err);
參數(shù)說明：pevent 是指向消息隊列的指針，該指針的值在建立該隊列時可以得到。(參考 OSQCreate() 函數(shù))。
timeout 允許一個任務以指定數(shù)目的時鐘節(jié)拍等待消息。超時后如果還沒有得到消息則恢復成就緒狀態(tài)。如果該值設置成零則表示任務將持續(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 設置為 OS_TIMEOUT。
3 OSQPostFront()
該函數(shù)用于向消息隊列發(fā)送消息。OSQPostFront() 函數(shù)和 OSQPost() 函數(shù)非常相似，不同之處在于 OSQPostFront() 函數(shù)將發(fā)送的消息插到消息隊列的最前端。也就是說，OSQPostFront() 函數(shù)使得消息隊列按照后入先出(LIFO)的方式工作，而不是先入先出(FIFO)。消息是一個指針長度的變量，在不同的應用中消息的含義也可能不同。如果隊列中已經(jīng)存滿消息，則此調(diào)用將返回錯誤碼。OSQPost() 函數(shù)也是如此。在調(diào)用此函數(shù)時如果有任何任務在等待隊列中的消息，則最高優(yōu)先級的任務將得到這個消息。如果等待消息的任務優(yōu)先級比發(fā)送消息的任務優(yōu)先級高，那么高優(yōu)先級的任務在得到消息后將立即搶占當前任務執(zhí)行，也就是說，將發(fā)生一次任務切換。
函數(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ā)送消息。消息是一個指針長度的變量，在不同的應用中消息的含義也可能不同。如果隊列中已經(jīng)存滿消息，則此調(diào)用返回錯誤碼。如果有任何任務在等待隊列中的消息，則最高優(yōu)先級的任務將得到這個消息。如果等待消息的任務優(yōu)先級比發(fā)送消息的任務優(yōu)先級高，那么高優(yōu)先級的任務將在得到消息后立即搶占當前任務執(zhí)行，也就是說，將發(fā)生一次任務切換。消息是以先入先出(FIFO)方式進入隊列的，即先進入隊列的消息先被傳遞給任務。
函數(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ù)結構，該結構用來保存從消息隊列的控制塊得到的數(shù)據(jù)。通過調(diào)用該函數(shù)可以知道是否有任務在等待消息、有多少個任務在等待消息、隊列中有多少消息以及消息隊列可以容納的消息數(shù)。OSQQuery() 函數(shù)還可以得到即將被傳遞給任務的消息。
函數(shù)原型：INT8U OSQQuery(OS_EVENT *pevent, OS_Q_DATA *pdata);
參數(shù)說明：pevent 是指向消息隊列的指針。該指針的值在建立消息隊列時可以得到。(參考 OSQCreate() 函數(shù))。
pdata 是指向 OS_Q_DATA 數(shù)據(jù)結構的指針，該數(shù)據(jù)結構包含下述成員：
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ù)用于刪除指定的消息隊列。
編輯：admin 最后修改時間：2018-05-18
