Z-Stack協(xié)議棧操作系統(tǒng)抽象層API

1、Z-Stack協(xié)議棧操作系統(tǒng)抽象層(OSAL) API操作系統(tǒng)抽象層(OSAL)是被用來(lái)使Z-Stack協(xié)議棧的軟件組件與特殊的出 來(lái)環(huán)境無(wú)關(guān)。操作系統(tǒng)抽象層能獨(dú)立于具體的出來(lái)環(huán)境，主要提供以下功能：1、任務(wù)的注冊(cè)，初始化和啟動(dòng)。2、任務(wù)間的消息交換。3、任務(wù)的同步。4、中斷處理。5、定時(shí)器處理。6、存儲(chǔ)器的分配。1消息管理API消息管理API為任務(wù)間或不同處理環(huán)境中的處理單元的消息交換提供一種 手段。消息管理API中的函數(shù)使能一個(gè)任務(wù)分配或者釋放消息緩沖區(qū)，發(fā)送命消 息給另一個(gè)任務(wù)并接收響應(yīng)消息。osal_msg_allocate()該函數(shù)被一個(gè)任務(wù)調(diào)用來(lái)分配一個(gè)消息緩沖區(qū)，該任務(wù)/函數(shù)將填

2、寫(xiě)消息并 通過(guò)調(diào)用osal_msg_send()函數(shù)來(lái)將消息發(fā)送給另一個(gè)任務(wù)。如果緩沖區(qū)不能被 分配，msg_ptr將被置位NULL。(注意：本函數(shù)被用來(lái)分配一個(gè)緩沖區(qū)以便在兩 個(gè)任務(wù)之間發(fā)送信息(使用osal_msg_send()函數(shù))。使用osal_mem_alloc()函 數(shù)是分配存儲(chǔ)器的一個(gè)塊。)。函數(shù)原型為：uint8 * osal_msg_allocate( uint16 len )其中參數(shù)：len為消息的長(zhǎng)度。函數(shù)返回值：一個(gè)指向?yàn)橄⒎峙涞木彌_區(qū)的指針。如果返回值為NULL表示操作失敗。osal_msg_deallocate()該函數(shù)被用來(lái)釋放一個(gè)消息緩沖區(qū)。當(dāng)一個(gè)任務(wù)(或處理

3、單元)在它已經(jīng)完 成對(duì)接收到的消息處理后調(diào)用本函數(shù)。函數(shù)原型為：uint8 osal_msg_deallocate( uint8 *msg_ptr )其中參數(shù)：msg_ptr為指向需要被釋放的消息緩沖區(qū)的指針。函數(shù)返回值：返回值描述SUCCESS釋放成功INVALID_MSG_POINTER無(wú)效的消息指針MSG_BUFFER_NOT_AVAIL緩沖區(qū)在排隊(duì)等候osal_msg_send()該函數(shù)被一個(gè)任務(wù)發(fā)送一個(gè)命令或數(shù)據(jù)信息到其他任務(wù)或處理元素中。destination_task標(biāo)識(shí)符字段必須指向一個(gè)有效的系統(tǒng)任務(wù)。當(dāng)調(diào)用 osal_create_task()函數(shù)來(lái)開(kāi)始一個(gè)任務(wù)的時(shí)候任務(wù)標(biāo)識(shí)

4、符被分配給該任務(wù)。本 函數(shù)將同時(shí)觸發(fā)目標(biāo)任務(wù)事件列表中的SYS_EVENT_MSG事件。函數(shù)原型為：uint8 osal_msg_send( uint8 destination_task, uint8 *msg_ptr )其中參數(shù)：destination_task為接收消息的任務(wù)ID。msg_ptr為指向包含消息的緩沖區(qū)的指針。該參數(shù)必須是通過(guò) osal_msg_allocate()函數(shù)分配的一個(gè)有效的緩沖區(qū)的指針。函數(shù)返回值：返回值描述SUCCESS消息發(fā)送成功INVALID_MSG_POINTER無(wú)效的消息指針I(yè)NVALID_TASKdestination_task 無(wú)效osal_msg_

5、receive()該函數(shù)被一個(gè)任務(wù)調(diào)用來(lái)取回一條已經(jīng)收到的命令信息。調(diào)用該函數(shù)的任務(wù) 必須在處理完消息后使用osal_msg_deallocate()函數(shù)來(lái)釋放消息緩沖區(qū)。函數(shù)原型為：uint8 *osal_msg_receive( uint8 task_id )其中參數(shù)：task_id為調(diào)用該函數(shù)的任務(wù)(消息被發(fā)往給它)的標(biāo)識(shí)符。函數(shù)返回值：一個(gè)指向一個(gè)包含消息的緩沖區(qū)的指針。如果沒(méi)有接收到消息 返回值為NULL。2任務(wù)同步API任務(wù)同步API可以使能一個(gè)任務(wù)去等待事件的發(fā)生并返回控制。任務(wù)同步 API中的函數(shù)可以被用來(lái)為一個(gè)任務(wù)設(shè)置事件，并且任何事件被觸發(fā)時(shí)通知該任 務(wù)。osal_set_

6、event()該函數(shù)被調(diào)用來(lái)為一個(gè)任務(wù)設(shè)置事件標(biāo)志。函數(shù)原型：uint8 osal_set_event( uint8 task_id, uint16 event_flag )其中參數(shù)：task_id將要被設(shè)置事件標(biāo)志的任務(wù)ID。event_flag為一個(gè)2字節(jié)的位圖，每位定義一個(gè)事件。僅有一個(gè)系統(tǒng)事件（SYS_EVENT_MSG ）其余事件/位被接收任務(wù)定義。函數(shù)返回值:返回值描述SUCCESS設(shè)置成功INVALID_MSG_POINTER源任務(wù)無(wú)效3定時(shí)器管理API定時(shí)器管理API使能內(nèi)部（Z-Stack）任務(wù)像外部（應(yīng)用級(jí)）任務(wù)一樣對(duì)定 時(shí)器的使用。定時(shí)器管理API中提供了一些函數(shù)去啟動(dòng)和

7、停止一個(gè)定時(shí)器。定時(shí) 器可以被設(shè)置成1毫秒的增量。3.1 osal_start_timerEx（）該函數(shù)被調(diào)用來(lái)啟動(dòng)一個(gè)定時(shí)器。當(dāng)定時(shí)器到期時(shí)，該特定事件對(duì)應(yīng)的位被 置位。事件將被在調(diào)用osal_start_timerEx函數(shù)的任務(wù)中被觸發(fā)。函數(shù)原型：uint8 osal_start_timerEx（ uint8 taskID, uint16 event_id, uint16 timeout_value ）其中參數(shù)：taskID當(dāng)定時(shí)器到期時(shí)獲得事件的這個(gè)任務(wù)的ID。event_id 一個(gè)用戶定義的事件位。定時(shí)器到期時(shí)，調(diào)用任務(wù)將被通知（事件）。timeout_value定時(shí)器事件被觸發(fā)以前的

8、總時(shí)間（以毫秒為單位）。函數(shù)返回值：返回值描述SUCCESS定時(shí)器啟動(dòng)成功NO_TIMER_AVAIL無(wú)法啟動(dòng)定時(shí)器osal_stop_timerEx()該函數(shù)被調(diào)用來(lái)停止一個(gè)已經(jīng)啟動(dòng)的定時(shí)器。如果成功，該函數(shù)為調(diào)用任務(wù) 取消定時(shí)器并阻止與該定時(shí)器相關(guān)的事件被觸發(fā)。使用osal_stop_timerEx函數(shù) 意味著定時(shí)器正運(yùn)行在調(diào)用osal_stop_timerEx函數(shù)的任務(wù)的上下文環(huán)境中。函數(shù)原型：uint8 osal_stop_timerEx( uint8 task_id, uint16 event_id )其中參數(shù)：task_id 一個(gè)任務(wù)ID，停止定時(shí)器就是為了這個(gè)任務(wù)而操作的。eve

9、nt_id將要被停止的定時(shí)器的標(biāo)識(shí)符(事件)。函數(shù)返回值：返回值描述SUCCESS定時(shí)器停止成功INVALID_EVENT_ID無(wú)效事件osal_GetSystemClock()該函數(shù)被調(diào)用來(lái)讀取系統(tǒng)時(shí)鐘。函數(shù)原型：uint32 osal_GetSystemClock( void )其中參數(shù)：無(wú)函數(shù)返回值：以毫秒為單位的系統(tǒng)時(shí)鐘。4中斷管理API中斷管理API可以使能一個(gè)任務(wù)去與外部中斷進(jìn)行接口。中斷管理API中的 函數(shù)允許一個(gè)任務(wù)去與每一個(gè)中斷關(guān)聯(lián)一個(gè)專門(mén)的服務(wù)例程。中斷可以被使能或 禁止。在中斷服務(wù)例程中。事件可被其他任務(wù)觸發(fā)。osal_int_enable()本函數(shù)被調(diào)用來(lái)使能一個(gè)中斷，

10、中斷一旦使能，發(fā)生中斷時(shí)，與該中斷相關(guān) 的服務(wù)例程將被調(diào)用。函數(shù)原型：uint8 osal_int_enable( uint8 interrupt_id )其中參數(shù)：interrupt_id將被使能的中斷的標(biāo)識(shí)符。函數(shù)返回值：返回值描述SUCCESS中斷使能成功INVALID_INTERRUPT_ID無(wú)效中斷osal_int_disable()本函數(shù)被調(diào)用來(lái)禁止一個(gè)中斷。當(dāng)一個(gè)被禁止的中斷發(fā)生時(shí)，與該中斷相關(guān) 的服務(wù)例程將不被調(diào)用。函數(shù)原型：uint8 osal_int_disable( uint8 interrupt_id )其中參數(shù)：interrupt_id將被禁止的中斷標(biāo)識(shí)符。函數(shù)返回值

11、：返回值描述SUCCESS中斷禁止成功INVALID_INTERRUPT_ID無(wú)效中斷5任務(wù)管理API任務(wù)管理API被用來(lái)在操作系統(tǒng)抽象層(OSAL)系統(tǒng)中添加和管理任務(wù)。osal_init_system()本函數(shù)初始化操作系統(tǒng)抽象層(OSAL)系統(tǒng)。在啟動(dòng)過(guò)程中，該函數(shù)必須在 使用其他任何OSAL函數(shù)OSAL函數(shù)之前被調(diào)用。函數(shù)原型：uint8 osal_init_system( void )其中參數(shù)：無(wú)函數(shù)返回值：SUCCESS成功osal_start_system()該函數(shù)是任務(wù)系統(tǒng)中的主循環(huán)函數(shù)。它查看所有的任務(wù)事件并為具有事件的 任務(wù)調(diào)用事件處理函數(shù)。如果特殊任務(wù)有事件，該函數(shù)將為這

12、個(gè)任務(wù)調(diào)用事件處 理例程來(lái)處理這些事件。相應(yīng)的任務(wù)的事件處理例程每次處理一個(gè)事件。在一個(gè) 事件被處理后，其余的事件將被返回到主循環(huán)中等待下一次處理。如果沒(méi)有事件 (多所有任務(wù)而言)，被函數(shù)將使處理器進(jìn)入睡眠模式。函數(shù)原型：void osal_start_system( void )其中參數(shù)：無(wú)函數(shù)返回值：無(wú)6存儲(chǔ)器管理API存儲(chǔ)器管理API是一個(gè)簡(jiǎn)單的存儲(chǔ)器分配系統(tǒng)。存儲(chǔ)器管理API中的函數(shù)允 許動(dòng)態(tài)存儲(chǔ)器分配。osal_mem_alloc()本函數(shù)是一個(gè)簡(jiǎn)單的存儲(chǔ)器分配函數(shù)，它返回一個(gè)指向一個(gè)緩沖區(qū)的指針 (如果成功)。函數(shù)原型：void *osal_mem_alloc( uint16 si

13、ze )其中參數(shù)：size希望獲得的緩沖區(qū)的字節(jié)數(shù)量。函數(shù)返回值：一個(gè)無(wú)效指針(應(yīng)該被分配給一個(gè)預(yù)期的緩沖區(qū)類(lèi)型)指向新 分配的緩沖區(qū)。若返回NULL指針，表示沒(méi)有足夠的存儲(chǔ)器來(lái)分配。6.2 osal_mem_free()本函數(shù)釋放已被分配的存儲(chǔ)器以便再次使用。本函數(shù)只能在存儲(chǔ)器已經(jīng)被使 用osal_mem_alloc()函數(shù)分配過(guò)的情況下工作。函數(shù)原型：void osal_mem_free( void *ptr )其中參數(shù)：ptr指向準(zhǔn)備被釋放的緩沖區(qū)的指針。該緩沖區(qū)先前必須已經(jīng)被分配(使用 osal_mem_alloc()函數(shù))。函數(shù)返回值：無(wú)7電源管理API操作系統(tǒng)抽象層(OSAL)的電

14、源管理系統(tǒng)為應(yīng)用/任務(wù)提供了一種方式：當(dāng) 安全的關(guān)閉了接收器和外部硬件并且使處理器處于睡眠狀態(tài)時(shí)去通知操作系統(tǒng) 抽象層(OSAL)。有兩個(gè)函數(shù)來(lái)控制電源管理。第一個(gè)，osal_pwrmgr_device()函數(shù)被調(diào)用來(lái) 設(shè)置設(shè)備的級(jí)別模式(節(jié)點(diǎn)模式或非節(jié)點(diǎn)模式)。然后是任務(wù)電源狀態(tài)，每一個(gè) 任務(wù)可以通過(guò)調(diào)用osal_pwrmgr_task_state(PWRMGR_HOLD)來(lái)阻止電源管理使 用節(jié)電模式。如果一個(gè)任務(wù)“控制”了電源管理，那么它將需要通過(guò)調(diào)用 osal_pwrmgr_task_state(PWRMGR_CONSERVE)來(lái)允許電源管理在節(jié)電模式下繼續(xù) 工作。默認(rèn)情況下，當(dāng)任務(wù)被初

15、始化時(shí)，每一個(gè)任務(wù)的電源狀態(tài)被設(shè)置為 PWRMGR_CONSERVE，因此如果一個(gè)任務(wù)不想阻止節(jié)電模式(狀態(tài)不改變)那就不 需要調(diào)用 osal_pwrmgr_task_state()函數(shù)。電源管理在進(jìn)入節(jié)電模式之前將查看設(shè)備模式和所有任務(wù)的電源狀態(tài)集合。osal_pwrmgr_device()本函數(shù)在上電時(shí)或者要求更換電源(例如，協(xié)調(diào)器背面的電池)時(shí)被調(diào)用。本函數(shù)設(shè)置設(shè)備的電源管理的全部開(kāi)/關(guān)狀態(tài)。本函數(shù)應(yīng)當(dāng)被一個(gè)中央控制 實(shí)體(如ZDO)調(diào)用。函數(shù)原型：void osal_pwrmgr_device( uint8 pwrmgr_device )其中參數(shù)：pwrmgr_device改變或者設(shè)置

16、電源節(jié)電模式，類(lèi)型為：類(lèi)型描述PWRMGR_ALWAYS_ON選擇該類(lèi)型將沒(méi)有節(jié)電模式，設(shè)備有電源供電PWRMGR_BATTERY打開(kāi)節(jié)電模式函數(shù)返回值：無(wú)osal_pwrmgr_task_state()本函數(shù)被每一個(gè)任務(wù)調(diào)用進(jìn)入一個(gè)狀態(tài)不管該任務(wù)是否想節(jié)電。任務(wù)將調(diào)用 本函數(shù)來(lái)決定是否它想讓操作系統(tǒng)抽象層(OSAL)節(jié)電或者不節(jié)電。默認(rèn)情況下， 當(dāng)一個(gè)任務(wù)被創(chuàng)建后，它自己的電源狀態(tài)被設(shè)置為節(jié)電，如果這個(gè)任務(wù)希望一直 保持節(jié)電，它不需要調(diào)用本函數(shù)。函數(shù)原型：uint8 osal_pwrmgr_task_state( uint8 task_id, uint8 state )其中參數(shù)：task_i

17、d 任務(wù) IDstate改變一個(gè)任務(wù)的電源狀態(tài)，state類(lèi)型：類(lèi)型描述PWRMGR_CONSERVE開(kāi)節(jié)電模式，所有任務(wù)必須同意。這是一個(gè)任 務(wù)初始化時(shí)的默認(rèn)狀態(tài)PWRMGR_HOLD關(guān)閉節(jié)電模式函數(shù)返回值:類(lèi)型描述SUCCESS成功INVALID_TASK無(wú)效任務(wù)8非易失性存儲(chǔ)器API操作系統(tǒng)抽象層（OSAL）的非易失性（NV）存儲(chǔ)器系統(tǒng)為應(yīng)用提供了一個(gè)將 信息持久的保存在設(shè)備的存儲(chǔ)器中的方式。它也被協(xié)議棧用來(lái)持久的存儲(chǔ) zigbee規(guī)范要求的必要項(xiàng)目。NV函數(shù)被設(shè)計(jì)用來(lái)讀和寫(xiě)用戶自定義的項(xiàng)目（由 任意數(shù)據(jù)類(lèi)型，例如結(jié)構(gòu)體或數(shù)據(jù)組成）。通過(guò)設(shè)置恰當(dāng)?shù)钠频刂泛烷L(zhǎng)度，用 戶可以讀或?qū)懸粋€(gè)完整

18、的項(xiàng)目或者項(xiàng)目的一個(gè)單元。非易失性存儲(chǔ)器API與NV 存儲(chǔ)介質(zhì)無(wú)關(guān)，可以在flash或EEPROM上實(shí)施。每一個(gè)NV項(xiàng)目有一個(gè)唯一的ID。應(yīng)用由一個(gè)特定的ID值范圍，其中的某些 ID值被保留或被協(xié)議?；虮婚_(kāi)發(fā)平臺(tái)所用。如果應(yīng)用需要?jiǎng)?chuàng)建自己的NV項(xiàng)目， 必須從應(yīng)用值范圍內(nèi)選擇一個(gè)ID，見(jiàn)下表：值用戶0 x0000保留0 x0001- 0 x0020操作系統(tǒng)抽象層0 x0021- 0 x0040網(wǎng)絡(luò)層0 x0041- 0 x0060應(yīng)用支持子層0 x0061- 0 x0080安全0 x0081- 0 x00A0ZigBee設(shè)備對(duì)象0 x00A1- 0 x0200保留0 x0201- 0 x0FFF

19、應(yīng)用0 x1000- 0 xFFFF保留在使用非易失性存儲(chǔ)器API時(shí)需要認(rèn)真考慮以下幾點(diǎn)：1、它們都是阻塞函數(shù)，一個(gè)操作可能需要數(shù)毫秒才能完成，與其是針對(duì)NV 的寫(xiě)操作。另外，中斷可能被禁止數(shù)毫秒。最好是在當(dāng)它不與其他時(shí)間關(guān)鍵性操 作沖突時(shí)執(zhí)行這些函數(shù)。例如，寫(xiě)NV項(xiàng)目的一個(gè)好時(shí)機(jī)是當(dāng)接收器關(guān)閉的時(shí)候。2、不要頻繁的進(jìn)行NV寫(xiě)操作。它耗時(shí)耗電，并且大多數(shù)flash設(shè)備都有一 個(gè)循環(huán)擦除的次數(shù)限制。3、如果一個(gè)或多個(gè)NV項(xiàng)目的結(jié)構(gòu)發(fā)生改變，特別是當(dāng)從Z-Stack的一個(gè)版 本升級(jí)到另一個(gè)版本，擦除和重新初始化NV存儲(chǔ)器時(shí)必要的。否則，在已改變 的NV項(xiàng)目上進(jìn)行讀和寫(xiě)操作將會(huì)失敗或產(chǎn)生錯(cuò)誤的結(jié)果。

20、osal_nv_item_init()本函數(shù)在NV中初始化一個(gè)項(xiàng)目。該函數(shù)檢查NV中的一個(gè)項(xiàng)目是否存在。如 果它不存在，它將被創(chuàng)建和用函數(shù)參數(shù)傳遞的數(shù)據(jù)初始化。在調(diào)用 osal_nv_read()或osal_nv_write()函數(shù)之前，本函數(shù)必須被每一個(gè)項(xiàng)目調(diào)用。函數(shù)原型：uint8 osal_nv_item_init( uint16 id, uint16 len, void *buf )其中參數(shù)：id用戶自定義ID。len項(xiàng)目長(zhǎng)度(以字節(jié)為單位)。buf指向項(xiàng)目初始化數(shù)據(jù)的指針。若沒(méi)有初始化數(shù)據(jù)，被置為NULL。函數(shù)返回值：返回值描述ZSUCCESS成功NV_ITEM_UNINIT成功但項(xiàng)

21、目不存在NV_OPER_FAILED操作失敗osal_nv_read()該函數(shù)從NV讀取數(shù)據(jù)。本函數(shù)可以被用來(lái)從NV讀取一個(gè)實(shí)體項(xiàng)目或讀取通過(guò)偏移索引到項(xiàng)目中的一個(gè)單元。讀取的數(shù)據(jù)拷貝到*buf。函數(shù)原型：uint8 osal_nv_read（ uint16 id, uint16 ndx, uint16 len, void *buf ）其中參數(shù)：id用戶自定義項(xiàng)目ID。ndx項(xiàng)目在存儲(chǔ)器中的偏移（以字節(jié)為單位）。len項(xiàng)目長(zhǎng)度（以字節(jié)為單位）。buf數(shù)據(jù)將被讀取到該緩沖區(qū)。函數(shù)返回值：返回值描述ZSUCCESS成功NV_ITEM_UNINIT項(xiàng)目未被初始化NV_OPER_FAILED操作失敗8

22、.3 osal_nv_write（）該函數(shù)為寫(xiě)數(shù)據(jù)到NV，本函數(shù)可以被用來(lái)寫(xiě)一個(gè)實(shí)體項(xiàng)目到NV或者寫(xiě)一個(gè) 通過(guò)偏移索引到項(xiàng)目中的一個(gè)單元到NV。函數(shù)原型：uint8 osal_nv_write（ uint16 id, uint16 ndx, uint16 len, void *buf ）其中參數(shù)：id用戶自定義項(xiàng)目ID。ndx項(xiàng)目在存儲(chǔ)器中的偏移（以字節(jié)為單位）。len項(xiàng)目長(zhǎng)度（以字節(jié)為單位）。buf數(shù)據(jù)將被寫(xiě)入到該緩沖區(qū)。函數(shù)返回值：返回值描述ZSUCCESS成功NV_ITEM_UNINIT項(xiàng)目未被初始化NV_OPER_FAILED操作失敗9協(xié)議棧操作系統(tǒng)抽象層（OSAL ）其他API內(nèi)存復(fù)

23、制函數(shù)：void *osal_memcpy( void *dst, const void GENERIC *src, unsigned int len ) 內(nèi)存倒置函數(shù)：void *osal_revmemcpy( void *dst, const void GENERIC *src, unsigned int len )內(nèi)存比較函數(shù)：uint8 osal_memcmp( const void GENERIC *src1, const void GENERIC *src2, unsigned int len )內(nèi)存分配函數(shù)：void *osal_memset( void *dest, uint8

24、 value, int len )隨機(jī)數(shù)生成函數(shù)：uint16 osal_rand( void )系統(tǒng)事件發(fā)現(xiàn)函數(shù)：osal_event_hdr_t *osal_msg_find(uint8 task_id, uint8 event)系統(tǒng)消息入列：void osal_msg_enqueue( osal_msg_q_t *q_ptr, void *msg_ptr )系統(tǒng)消息出列：void *osal_msg_dequeue( osal_msg_q_t *q_ptr )刪除事件函數(shù)：uint8 osal_clear_event( uint8 task_id, uint16 event_flag )中斷注冊(cè)函數(shù)：uint8 osal_isr_register( uint8 interrupt_id, void (*isr_ptr)( uint8* )更新系統(tǒng)時(shí)間：void osalTimeUpdate( void )系統(tǒng)時(shí)鐘更新：static void osalClockUpdate( uint16 elapsedMSec )設(shè)置系統(tǒng)時(shí)鐘