ZigBee_CC2530_09H_API函數(shù)

? Zstack協(xié)議棧依靠協(xié)議棧內(nèi)部的OS(即OSAL)才能運(yùn)行起來(lái)，OSAL提供的服務(wù)和管理包括：信息管理、任務(wù)同步、時(shí)間管理、中斷管理、任務(wù)管理、內(nèi)存管理、電源管理以及非易失存儲(chǔ)管理。

1. 信息管理API

? 信息管理API為任務(wù)和處理單元之間的信息交換提供了一種具有不同處理環(huán)境的機(jī)制(例如，在一個(gè)控制循環(huán)中調(diào)用中斷服務(wù)常規(guī)程序或函數(shù))。這個(gè)API中國(guó)的函數(shù)可以使任務(wù)分配或回收信息緩沖區(qū)，給其他任務(wù)發(fā)送任務(wù)信息以及接受回復(fù)信息。

1.1 osal_msg_allocate()

? 這個(gè)函數(shù)被一個(gè)任務(wù)調(diào)用去分配一個(gè)信息緩沖，這個(gè)任務(wù)/函數(shù)將填充這個(gè)信息并且調(diào)用osal_msg_send()發(fā)送消息到另一個(gè)任務(wù)中。函數(shù)原型如下：

????uint8?*osal_msg_allocate(?uint16?len?);

? 參數(shù)描述：

??? len是信息的長(zhǎng)度。

? 返回值：返回值是指向一個(gè)信息分配的緩沖區(qū)的指針。一個(gè)空值的返回表明信息分配操作失敗。

1.2 osal_msg_deallocate()

? 這個(gè)函數(shù)用來(lái)回收一個(gè)信息緩沖區(qū)，在完成處理一個(gè)接受信息后這個(gè)函數(shù)被一個(gè)任務(wù)(或處理機(jī)單元)低啊用。函數(shù)原型如下：

????uint8?osal_msg_deallocate(byte?*msg_ptr);

? 參數(shù)描述：

msg_ptr是指向必須回收的信息緩沖的指針。

? 返回值：返回值指示了操作的結(jié)果。

ZSUCCESS：分配成功；

INVALID_MSG_POINTER：無(wú)效的信息指針；

MSG_BUFFER_NOT_AVAIL：緩沖區(qū)隊(duì)列。

1.3 osal_msg_send()

? 這個(gè)函數(shù)的功能是被一個(gè)任務(wù)調(diào)用，給另一個(gè)任務(wù)或者處理單元發(fā)送命令或數(shù)據(jù)信息。函數(shù)原型如下：

????uint8?osal_msg_send(?byte?destination_task?,?byte?*msg_ptr);

? 參數(shù)描述：

destination_task是接收信息任務(wù)的ID。

msg_ptr是指向必須包含信息的緩沖區(qū)的指針。msg_ptr必須執(zhí)行osal_msg_allocate()分配的一個(gè)有效緩沖區(qū)。

? 返回值：返回值是一個(gè)字節(jié)，表明操作的結(jié)果。

ZSUCCESS：分配成功；

INVALID_MSG_POINTER：無(wú)效的信息指針；

INVALID_TASK：destination_task是無(wú)效的。

1.4 osal_msg_receive()

? 此函數(shù)被一個(gè)任務(wù)調(diào)用來(lái)檢索一條已經(jīng)收到的命令信息。調(diào)用osal_msg_receive()處理信息后，必須回收信息緩沖區(qū)。函數(shù)原型如下：

????uint8?*osal_msg_receive(?byte?task_id);

? 參數(shù)描述：task_id是調(diào)用任務(wù)(信息指定的)的標(biāo)識(shí)符。

? 返回值：返回值是一個(gè)指向包含該信息的緩沖區(qū)的指針，如果沒(méi)有已接收的信息，返回值為空(NULL)。

2. 任務(wù)同步API

? 任務(wù)同步API使得任務(wù)等待事件發(fā)送，并在等待期間返回控制。這個(gè)API中的函數(shù)可以用來(lái)為一個(gè)任務(wù)設(shè)置事件，無(wú)論設(shè)置了什么事件都通知任務(wù)。

? 通過(guò)osal_set_event()這個(gè)函數(shù)調(diào)用，為一個(gè)任務(wù)設(shè)置事件的標(biāo)志。其函數(shù)原型如下：

????uint8?osal_set_event(?byte?task_id?,?UINT16?event_flag?);

? 參數(shù)描述：

task_id是設(shè)置事件的任務(wù)的標(biāo)識(shí)符。

event_flag是兩個(gè)字節(jié)的位圖且每個(gè)位詳述了一個(gè)事件。這僅有一個(gè)系統(tǒng)事件(SYS_EVENT_MSG),其余事件/位都是通過(guò)接收任務(wù)來(lái)規(guī)定的。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：成功；

INVALID_TASK：無(wú)效事件；

3. 定時(shí)器管理API

? 定時(shí)器管理API使Zstack內(nèi)部的任務(wù)和外部的應(yīng)用層任務(wù)都可以使用定時(shí)器。API提供了啟動(dòng)和停止一個(gè)定時(shí)器的功能，這個(gè)定時(shí)器可設(shè)定遞增的一毫秒。

3.1 osal_start_timer()

? 啟動(dòng)一個(gè)定時(shí)器時(shí)調(diào)用此函數(shù)。當(dāng)定時(shí)器終止時(shí)，給定的事件位將設(shè)置。這個(gè)事件通過(guò)osal_start_timer()函數(shù)調(diào)用，將在任務(wù)中設(shè)置。函數(shù)原型如下：

????uint8?osal_start_timer(?UINT16?event_id?,?UINT16?timeout_value);

? 參數(shù)描述：

event_id是用戶確定事件的ID。當(dāng)定時(shí)器終止時(shí)，該事件將被觸發(fā)。

timeout_value指定時(shí)器事件設(shè)置之前的時(shí)長(zhǎng)(以毫秒為單位)。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：成功；

NO_TIMER_AVAILABLE：沒(méi)有能夠啟動(dòng)定時(shí)器；

3.2 osal_start_timerEx() ? 類似于osal_start_timer()，增加了taskID參數(shù)。允許訪問(wèn)這個(gè)調(diào)用程序?yàn)榱硪粋€(gè)任務(wù)設(shè)置定時(shí)器。函數(shù)原型如下：

????uint8?osal_start_timerEx(?byte?taskID?,?UINT16?event_id?,?UINT16?timerout_value?);

? 參數(shù)描述：

taskID是定時(shí)器終止時(shí)，獲取該事件任務(wù)的ID。

event_id是用戶確定事件的ID。當(dāng)定時(shí)器終止時(shí)，該事件將被觸發(fā)。

timeout_value指定時(shí)器事件設(shè)置之前的時(shí)長(zhǎng)(以毫秒為單位)。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：成功；

NO_TIMER_AVAILABLE：沒(méi)有能夠啟動(dòng)定時(shí)器；

3.3 osal_stop_timer()

??? 此函數(shù)用來(lái)停止一個(gè)已啟動(dòng)的定時(shí)器，如果成功，函數(shù)將取消定時(shí)器并阻止設(shè)置調(diào)用程序中與定時(shí)器有關(guān)的時(shí)間。使用osal_stop_timer()函數(shù)，意味著調(diào)用osal_stop_timer()的任務(wù)中定時(shí)器正在運(yùn)行。函數(shù)原型如下：

????uint8?osal_stop_timer(?UINT16?event_id?);

? 參數(shù)描述：

event_id是要停止的計(jì)時(shí)器的標(biāo)識(shí)符。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：關(guān)閉定時(shí)器成功；

INVALID_EVENT_ID：無(wú)效事件；

3.3 osal_stop_timerEx() ? 此函數(shù)功能是在不同的任務(wù)中中止定時(shí)器的，與osal_stop_timer()函數(shù)類似，只是指明了任務(wù)ID。函數(shù)原型如下：

????uint8?osal_stop_timerEx(?byte?task_id?,?UINT16?event_id?);

? 參數(shù)描述：

task_id：停止定時(shí)器所在的任務(wù)ID。

event_id：要停止的計(jì)時(shí)器的標(biāo)識(shí)符。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：關(guān)閉定時(shí)器成功；

INVALID_EVENT_ID：無(wú)效事件；

3.5 osal_GetSystemClock()

? 此函數(shù)功能為讀取系統(tǒng)時(shí)鐘。函數(shù)原型如下：

????uint8?osal_GetSystemClock(?void?);

? 返回值為以毫秒為單位的系統(tǒng)時(shí)鐘。
4. 中斷管理API

? 中斷管理API可以使一個(gè)任務(wù)與外部中斷互相交流。API中的函數(shù)允許和每個(gè)中斷去聯(lián)絡(luò)一個(gè)具體的服務(wù)流程。中斷可以啟用或禁用，在服務(wù)例程內(nèi)部，可以為其他任務(wù)設(shè)置事件。

4.1 osal_int_enable()

? 此函數(shù)的功能是啟用一個(gè)中斷，中斷一旦啟用將調(diào)用與該中斷相聯(lián)系的服務(wù)例程。函數(shù)原型如下：

????uint8?osal_int_enable(?byte?interrupt_id?);

? 參數(shù)描述：

interrupt_id：指明要啟用的中斷。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：開啟中斷成功；

INVALID_INTERRUPT_ID：無(wú)效中斷；

4.2 osal_int_disable()

? 此函數(shù)的功能是禁用一個(gè)中斷，當(dāng)禁用一個(gè)中斷時(shí)，與該中斷相聯(lián)系的服務(wù)例程將不被調(diào)用。函數(shù)原型如下：

????uint8?osal_int_enable(?byte?interrupt_id?);

? 參數(shù)描述：

interrupt_id：指明要禁用的中斷。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：關(guān)閉中斷成功；

INVALID_INTERRUPT_ID：無(wú)效中斷；

5. 任務(wù)管理API

? 在OSAL系統(tǒng)中，API常用語(yǔ)添加和管理任務(wù)。每個(gè)任務(wù)由初始化函數(shù)和時(shí)間處理函數(shù)組成。

5.1 osal_init_system()

? 此函數(shù)功能為初始化OSAL系統(tǒng)。在使用任何其他OSAL函數(shù)之前必須先調(diào)用此函數(shù)啟動(dòng)OSAL系統(tǒng)。函數(shù)原型為：

????uint8?osal_init_system(?void?);

? 參數(shù)描述：

無(wú)。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：初始OSAL系統(tǒng)成功；

5.2 osal_start_system()

? 此函數(shù)是任務(wù)系統(tǒng)中的主循環(huán)函數(shù)。它將仔細(xì)檢查所有的任務(wù)事件，并且為含有該事件的任務(wù)調(diào)用任務(wù)事件處理函數(shù)。如果有特定任務(wù)事件，這個(gè)函數(shù)將為該任務(wù)調(diào)用事件處理例程來(lái)處理事件。相應(yīng)任務(wù)的事件處理例程一次處理一個(gè)事件。一個(gè)事件被處理后，剩余事件將等待下一次循環(huán)。如果沒(méi)有時(shí)間，這個(gè)函數(shù)時(shí)處理器程序處于睡眠模式。函數(shù)原型為：

????uint8?osal_start_system(?void?);

? 參數(shù)描述：

無(wú)。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：成功；

6. 內(nèi)存管理API

? 內(nèi)存管理API代表一個(gè)簡(jiǎn)單的內(nèi)存分配系統(tǒng)。這些函數(shù)允許動(dòng)態(tài)存儲(chǔ)內(nèi)存分配。

6.1 osal_mem_alloc()

? 此函數(shù)是一個(gè)內(nèi)存分配函數(shù)，如果分配內(nèi)存成功，返回一個(gè)指向緩沖區(qū)的指針。函數(shù)原型如下：

????void?*osal_mem_alloc(?uint16?size?);

? 參數(shù)描述：

size：要求的緩沖區(qū)字節(jié)數(shù)值。

? 返回值：

指向新分配的緩沖區(qū)的空指針(應(yīng)指向目的緩沖類型)。

如果沒(méi)有足夠的內(nèi)存可分配，將返回NULL指針。

6.2 osal_mem_free()

? 此函數(shù)用于釋放存儲(chǔ)空間，便于被釋放的存儲(chǔ)空間的再次使用，僅在內(nèi)存已經(jīng)通過(guò)調(diào)用osal_mem_alloc()被分配后才有效。函數(shù)原型如下：

????void?osal_mem_free(?void?*ptr?);

參數(shù)描述：

ptr：指向要釋放的緩沖區(qū)的指針。這個(gè)緩沖區(qū)必須在之前調(diào)用osal_mem_alloc()已被分配，為以前分配的空間。

? 返回值：

???????????? 無(wú)。
7. 電源管理API

? 當(dāng)安全關(guān)閉接收器或外部硬件時(shí)，電源管理API為應(yīng)用程序或任務(wù)提供了告知OSAL的方法，使處理器轉(zhuǎn)入睡眠狀態(tài)。

? 電源管理API有2個(gè)函數(shù)：osal_pwrmgr_device()和osal_pwrmgr_task_state()。第一個(gè)函數(shù)時(shí)設(shè)置設(shè)備的模式；第二個(gè)為電源狀態(tài)管理。

7.1 osal_pwrmgr_device()

? 當(dāng)升高電源或需要改變電源時(shí)(例如：電池支持的協(xié)調(diào)器)，這個(gè)函數(shù)應(yīng)有中心控制實(shí)體(比如ZDO)調(diào)用。函數(shù)原型如下：

????void?osal_pwrmgr_device(?byte?pwrmgr_device);

? 參數(shù)描述：

pwrmgr_device：改變和設(shè)置電源的節(jié)省模式。

PWRMGR_ALWAYS_ON：沒(méi)有省電模式，設(shè)備可能使用主電源供電。

PWRMGR_BATTERY：打開省電模式。

? 返回值：

???????????? 無(wú)。

7.2 osal_pwrmgr_task_state()

? 每個(gè)任務(wù)都將調(diào)用此函數(shù)。此函數(shù)的功能是用來(lái)表決是否需要OSAL電源保護(hù)或推遲電源保護(hù)。當(dāng)一個(gè)任務(wù)被創(chuàng)建時(shí)，默認(rèn)情況下電源狀態(tài)設(shè)置為保護(hù)模式。如果該任務(wù)一直想保護(hù)電源，就不必調(diào)用該函數(shù)。函數(shù)原型如下：

????void?osal_pwrmgr_task_state(?bytetask_id?,?byte?state);

? 參數(shù)描述：

state：改變一個(gè)任務(wù)的電源狀態(tài)。

PWRMGR_CONSERVE：打開省電模式，所有事件必須允許。事件初始化時(shí)，此狀態(tài)位默認(rèn)狀態(tài)。

PWRMGR_HOLD：關(guān)閉省電模式。

? 返回值：

???????????? ZSUCCESS：成功。

INVALID_TASK：無(wú)效事件。

8.非易失性存儲(chǔ)管理API

? 非易失性存儲(chǔ)器API為應(yīng)用程序提供了一種吧信息永久保存到設(shè)備內(nèi)存的方法。它還能用于把Zigbee規(guī)范要求的某些項(xiàng)目永久保存到協(xié)議棧。NV函數(shù)的功能是讀寫任意數(shù)據(jù)類型的用戶自定義項(xiàng)目，比如結(jié)構(gòu)體和數(shù)組。用戶能通過(guò)設(shè)置合適的偏移和長(zhǎng)度來(lái)讀寫一個(gè)整體的項(xiàng)目或元素。API獨(dú)立于NV存儲(chǔ)介質(zhì)，并且能用于實(shí)現(xiàn)閃存或EEPROM。

? 每個(gè)易失性的項(xiàng)目都僅有一個(gè)ID，當(dāng)一些ID由?；蚱脚_(tái)保留或運(yùn)用時(shí)，應(yīng)用程序中有特定的一系列ID值。加入應(yīng)用程序創(chuàng)建自己的易失性項(xiàng)目，它必須從應(yīng)用范圍的值內(nèi)選擇一個(gè)標(biāo)識(shí)符。如表所示：

值 使用者 0x0000 保留 0x0001-0x0020 操作系統(tǒng)抽象層 0x0021-0x0040 網(wǎng)絡(luò)層 0x0041-0x0060 應(yīng)用支持子層 0x0061-0x0080 安全 0x0081-0x00A0 Zigbee設(shè)備對(duì)象 0x00A1-0x0200 保留 0x0201-0x0FFF 應(yīng)用程序 0x1000-0xFFFF 保留 ? 運(yùn)用API時(shí)需要注意以下幾個(gè)方面：

有一些模塊化調(diào)用函數(shù)，操作系統(tǒng)可能需要較短的時(shí)間來(lái)完成(例如幾毫秒的時(shí)間)，尤其是對(duì)NV寫入操作。

盡量不要頻繁地執(zhí)行NV寫入操作。

結(jié)構(gòu)體中一個(gè)或多個(gè)NV項(xiàng)目改變，尤其是從一個(gè)Zstack版本升級(jí)至另一個(gè)版本時(shí)，必須擦除和重新初始化NV內(nèi)存。否則，修改NV項(xiàng)目的讀寫操作將失敗，或產(chǎn)生錯(cuò)誤結(jié)果。

8.1 osal_nv_item_init()

? 此函數(shù)用于初始化NV項(xiàng)目，用于檢查存在的NV的項(xiàng)目。如果不存在，它將通過(guò)這個(gè)函數(shù)去創(chuàng)建或初始化。假如存在，再調(diào)用osal_nv_read()或osal_nv_write()之前，每個(gè)項(xiàng)目都應(yīng)調(diào)用此函數(shù)。函數(shù)原型如下：

????uint8?osal_nv_item_init(?uint16?id?,?uint16?len?,?void?*buf);

? 參數(shù)描述：

id：用戶自定義項(xiàng)的ID。

len：項(xiàng)目字節(jié)長(zhǎng)度。

*buf：初始化數(shù)據(jù)指針。如沒(méi)初始化數(shù)據(jù)，則設(shè)置為空。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：成功；

NV_ITEM_UNINIT：對(duì)象沒(méi)初始化；

NV_OPER_FAILED：操作失敗。

8.2 osal_nv_read()

? 此函數(shù)用于從NV中讀出數(shù)據(jù)，用于從NV中帶用偏移的索引指向的項(xiàng)目中讀出整個(gè)項(xiàng)目或一個(gè)元素，讀出數(shù)據(jù)復(fù)制到*buf中。函數(shù)原型如下：

????uint8?osal_nv_read(?uint16?id?,?uint16?offset?,uint16?len?,?void?*buf);

? 參數(shù)描述：

id：用戶自定義項(xiàng)的ID。

offset：以字節(jié)為單位到項(xiàng)目的存儲(chǔ)偏移量

len：項(xiàng)目字節(jié)長(zhǎng)度。

*buf：數(shù)據(jù)讀取到緩沖區(qū)。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：成功；

NV_ITEM_UNINIT：對(duì)象沒(méi)初始化；

NV_OPER_FAILED：操作失敗。

8.3 osal_nv_write()

? 此函數(shù)用于寫入數(shù)據(jù)到NV中，用于從NV中帶用偏移的索引指向的項(xiàng)目中寫入整到整個(gè)NV項(xiàng)目中。函數(shù)原型如下：

????uint8?osal_nv_write(?uint16?id?,?uint16?offset?,uint16?len?,?void?*buf);

? 參數(shù)描述：

id：用戶自定義項(xiàng)的ID。

offset：以字節(jié)為單位到項(xiàng)目的存儲(chǔ)偏移量

len：項(xiàng)目字節(jié)長(zhǎng)度。

*buf：數(shù)據(jù)寫入到緩沖區(qū)。

? 返回值：返回值指示操作的結(jié)果。

ZSUCCESS：成功；

NV_ITEM_UNINIT：對(duì)象沒(méi)初始化；

NV_OPER_FAILED：操作失敗。

8.4 osal_offsetof()

? 此函數(shù)用于計(jì)算一個(gè)結(jié)構(gòu)體內(nèi)元素的偏移量，以字節(jié)為單位。用它來(lái)計(jì)算NV API函數(shù)使用的參數(shù)的偏移量。函數(shù)原型如下：

????uint8?osal_offsetof(?type?,?member);

? 參數(shù)描述：

????????????? type：結(jié)構(gòu)體類型。

???????????? member：結(jié)構(gòu)體成員

? 返回值：

??????????? 無(wú)。