uC/OS-II中的消息郵箱2007-09-03 10:24最近在學(xué)習(xí)UCOS-II，為了自已方便，我把UCOS-II內(nèi)核程序都做了一個(gè)注釋，雖然不夠完整，但對(duì)學(xué)習(xí)也是有一定幫助的，我把它放在這里，希望對(duì)大家有所幫助吧。所有的注釋我會(huì)陸續(xù)放在這里的。敬請(qǐng)關(guān)注。 消息郵箱是uC/OS-II中的另一種通信機(jī)制，可以使一個(gè)任務(wù)或者中斷服務(wù)子程序向另一個(gè)任務(wù)發(fā)送一個(gè)指針型的變量。通常該指針指向一個(gè)包含了“消息”的特定數(shù)據(jù)結(jié)構(gòu)。
　　應(yīng)用程序可以使用多少個(gè)郵箱，其最大數(shù)目是由OS_CFG.H文件中的配置常數(shù)OS_MAX_EVENTS設(shè)定。
任務(wù)或者中斷服務(wù)子程序都可以調(diào)用函數(shù)OSMboxPost()，OSMboxPostOpt() ，而只有任務(wù)可以調(diào)用OSMboxDel()
OSMboxPend()， OSMboxQuery()。
void   *OSMboxAccept (OS_EVENT *pevent)
　　無等待的從郵箱中得到一則消息。
OS_EVENT   *OSMboxCreate (void *msg)
　　建立一個(gè)郵箱。
　　msg:用來初始化建立的消息郵箱，如果該指針不為空，則建立的消息郵箱將含有消息。
　　返回值：指向分配給所建立的消息郵箱的事件控制塊的指針。如果沒有可用的事件控制塊，則返回空指針。
OS_EVENT   *OSMboxDel (OS_EVENT *pevent, INT8U opt, INT8U *err)
　　刪除一個(gè)郵箱。當(dāng)將OS_CFG.H文件中的OS_MBOX_DEL_EN設(shè)為1時(shí)，該函數(shù)才會(huì)被編譯。使用該函數(shù)時(shí)要注意，多個(gè)任務(wù)可能試圖操作已經(jīng)刪除的郵箱。在刪除郵箱之前，必須首先刪除可能操作該郵箱的所有任務(wù)。
　　pevent:指向郵箱的指針。該指針是在郵箱建立時(shí)返回給用戶應(yīng)用程序的指針。
　　opt:該先項(xiàng)定義郵箱的刪除條件，可以選擇只能在已經(jīng)沒有任何在等待該郵箱的消息時(shí)，才能刪除郵箱
         (OS_DEL_NO_PEND)；或者不管有沒有任務(wù)在等待郵箱的消息，立即刪除郵箱（OS_DEL_ALWAYS)，在這種情況   下，所有等待郵箱消息的任務(wù)都會(huì)立即進(jìn)入就緒態(tài)。
err:指向出錯(cuò)代碼的指針。返回的出錯(cuò)代碼可以是以下幾種情況之一。
　　OS_NO_ERR    調(diào)用成功，郵箱已經(jīng)被刪除。
　　OS_ERR_DEL_ISR   試圖在中斷服務(wù)子程序中刪除郵箱。
　　OS_ERR_INVALID_OPT 無效的opt參數(shù)，用戶沒有將opt定義為上述兩種情況之一。
　　OS_ERR_EVENT_TYPE pevent不是指向郵箱的指針。
　　OS_ERR_PEVENT_NULL 已經(jīng)沒有OS_EVENT數(shù)據(jù)結(jié)構(gòu)可以使用。
返回值：返回NULL表示郵箱已被刪除；返回pevent表示郵箱沒有刪作，。
void   *OSMboxPend (OS_EVENT *pevent, INT16U timeout, INT8U *err)
　　等待郵箱中的消息。
pevent:指向即將接收消息的消息郵箱的指針。
timeout:允許一個(gè)任務(wù)在經(jīng)過了指定數(shù)目的時(shí)鐘節(jié)拍后還沒有得到需要的消息時(shí)恢復(fù)運(yùn)行。如果該值為0表示任務(wù)將持續(xù)等待消息。
err:指向包含錯(cuò)誤碼的變量的指針。該函數(shù)返回的錯(cuò)誤碼可能為下述幾種情況
　　OS_NO_ERR    消息被正確地接收。
　　OS_TIMEOUT    消息沒有在指定的等待時(shí)間內(nèi)送到。
　　OS_ERR_EVENT_TYPE pevent不是指向消息郵箱的指針。
　　OS_ERR_PEND_ISR   從中斷調(diào)用該函數(shù)。
　　OS_ERR_PEVENT_NULL　pevent是空指針。
　　返回值：該函數(shù)返回接收的消息并將*err置為OS_NO_ERR.
INT8U   OSMboxPost (OS_EVENT *pevent, void *msg)
　　向郵箱發(fā)送一則消息。
     pevent:指向即將接收消息的消息郵箱的指針。
msg:即將實(shí)際發(fā)送給任務(wù)的的消息。消息是一個(gè)以指針表示的苛種數(shù)據(jù)類型的變量，在不同的程序中消息的使用也可能不同。不允許傳遞一個(gè)空指針，國(guó)灰這意味著消息郵箱為空。
返回值：該函數(shù)的返回值為下述之一：
　　　OS_NO_ERR    消息成功地放到消息郵箱中。
　　　OS_MBOX_FULL   消息郵箱已經(jīng)包含了其他消息，已滿。
　　　OS_ERR_EVENT_TYPE   pevent不是指向消息郵箱的指針。
　　　OS_ERR_PEVENT_NULL pevent是空指針。
　　　OS_ERR_POST_NULL_PTR   用戶試圖發(fā)出空指針。根據(jù)規(guī)則，在這里不支持空指針。
INT8U   OSMboxPostOpt (OS_EVENT *pevent, void *msg, INT8U opt)
　　向郵箱發(fā)送一則消息。該函數(shù)可以向等待郵箱的所有任務(wù)發(fā)送消息（廣播）。
　　pevent:指向即將接收消息的消息郵箱的指針。
　　msg:即將實(shí)際發(fā)送給任務(wù)的消息。消息是一個(gè)以指針表示的某種數(shù)據(jù)類型的變量，在不同的程序中消息的使用也可能不同。不允許傳遞一個(gè)空指針，因?yàn)檫@意味著消息郵箱為空。
　　opt:定義消息只發(fā)給等待郵箱消息的任務(wù)中優(yōu)先級(jí)最高的任務(wù)（將opt置為OS_POST_OPT_NONE)，或者讓所有等待 郵箱消息的任務(wù)都得到消息（將opt置為OS_POST_OPT_BROADCAST)。
　　返回值：
　　　err   指向包含錯(cuò)誤碼的變量指針，返回的錯(cuò)誤碼可能為下述幾種之一：
　　　     OS_NO_ERR    消息成功地放到消息郵箱中。
　　　OS_MBOX_FULL   消息郵箱已經(jīng)包含了其他消息，已滿。
　　　OS_ERR_EVENT_TYPE   pevent不是指向消息郵箱的指針。
　　　OS_ERR_PEVENT_NULL pevent是空指針。
　　　OS_ERR_POST_NULL_PTR   用戶試圖發(fā)出空指針。根據(jù)規(guī)則，在這里不支持空指針。  
INT8U   OSMboxQuery (OS_EVENT *pevent, OS_MBOX_DATA *p_mbox_data)
　　查詢一個(gè)郵箱的狀態(tài)。
　　pevent:指向即將接收消息的消息郵箱的指針。
　　pdata:指向OS_MBOX_DATA數(shù)據(jù)結(jié)構(gòu)的指針，該數(shù)據(jù)結(jié)構(gòu)包含下述成員。
　　　　　void   *OSMsg；       /*消息郵箱中消息的復(fù)制*/
　   　INT8U   OSEventTbl[OS_EVENT_TBL_SIZE];   /*消息郵箱等待隊(duì)列的復(fù)制*/
   　INT8U   OSEventGrp
返回值：該函數(shù)返回值為下述之一：
   　OS_NO_ERR     調(diào)用成功
   　OS_ERR_EVENT_NULL   pevent是空指針
   　OS_ERR_EVENT_TYPE   pevent不是指向消息郵箱的指針。