1. 信息管理API
信息管理為任務(wù)間的信息交換或者外部處理事件（例如：中斷服務(wù)程序或一個控制循環(huán)內(nèi)的函數(shù)調(diào)用）提供一種管理機制。包括允許任務(wù)分配或不分配信息緩存、發(fā)送命令信息到其他任務(wù)、接受應(yīng)答信息等API函數(shù)。
（1)osal_msg_allocate ( )
功能描述：
為信息分配緩存空間、任務(wù)調(diào)用或函數(shù)被調(diào)用的時候，該空間被信息填充或調(diào)用發(fā)送信息函數(shù)osal_msg_send()發(fā)送緩存空間的信息到其他任務(wù)。
原型：
byte *osal_msg_allocate( uint16 len )
參數(shù)：
len ：消息的長度
返回值：
指向消息緩沖區(qū)的指針，當分配失敗時返回NULL
注意：不能與函數(shù)osal_mem_alloc()混淆，osal_mem_alloc()函數(shù)被用于為在任務(wù)間發(fā)送信息分配緩沖區(qū)，用該函數(shù)也可以分配一個存儲區(qū)。
（2）osal_msg_deallocate( )
功能描述：
用于收回緩沖區(qū)
原型：
byte osal_msg_deallocate( byte *msg_ptr )
參數(shù)：
Msg_ptr : 指向?qū)⒁栈氐木彌_區(qū)的指針
返回值：
ZSUCCESS 回收成功
INVALID_MSG_POINTER 錯誤的指針
MSG_BUFFER_NOT_AVAIL 緩沖區(qū)在隊列中
（3） osal_msg_send( )
功能描述：
任務(wù)調(diào)用這個函數(shù)以實現(xiàn)發(fā)送指令或數(shù)據(jù)給另一個任務(wù)或處理單元。目標任務(wù)的標識必須是一個有效的系統(tǒng)任務(wù)，當調(diào)用osal_create_task ( )啟動一個任務(wù)時，將會分配任務(wù)標識。
osal_msg_send()也將在目標任務(wù)的事件列表中設(shè)置SYS_EVENT_MSG
原型：
byte osal_msg_send( byte destination_task, byte *msg_ptr )
參數(shù)：
destination_task ：目標任務(wù)的標識
msg_ptr ： 指向消息緩沖區(qū)的指針，必須是osal_msg_allocate ( )函數(shù)分配的有效的數(shù)據(jù)緩存
返回值：
返回一個字節(jié)，指示操作的結(jié)果.
ZSUCCESS 消息發(fā)送成功
INVALID_MSG_POINTER 無效指針
INVALID_TASK 目標任務(wù)無效
(4) osal_msg_receive( )
功能描述：
任務(wù)調(diào)用這個函數(shù)來接收消息。消息處理完畢后，發(fā)送消息的任務(wù)必須調(diào)用osal_msg_deallocate()收回緩沖區(qū)。一個任務(wù)接收一個命令信息是，調(diào)用該函數(shù)
原型：
byte *osal_msg_receive( byte task_id )
參數(shù)：
task_id ：消息發(fā)送者的任務(wù)標識
返回值：
指向消息所存放的緩沖區(qū)指針，如果沒有收到消息將返回NULL。
2 同步任務(wù)API
這個API使能一個任務(wù)等待一個事件的發(fā)生和返回控制而不是一直等待。在這個API中的函數(shù)可以用來為任務(wù)設(shè)置事件，立刻通知任務(wù)有事件被設(shè)置。
osal_set_event( )
功能描述：
函數(shù)用來設(shè)置一個任務(wù)的事件標志
原型：
byte osal_set_event( byte task_id, UINT16 event_flag )
參數(shù)：
task_id ：任務(wù)標識
event_flag�。菏牵矀�字節(jié)的位圖，每個位特指一個事件。只有一個系統(tǒng)事件（SYS_EVENT_MSG），其他事件在接收任務(wù)中定義。
返回值：
ZSUCCESS 成功設(shè)置
INVALID_TASK 無效任務(wù)
3.. 時間管理API
這個ＡＰＩ允許內(nèi)部任務(wù)（Z-Stack）以及應(yīng)用層任務(wù)使用定時器。函數(shù)提供了啟動和停止定時器的功能，定時器最小增量為1MS。
（1） osal_start_timer( )
功能描述：
啟動一個定時器，當定時器終止時，指定的事件標志位被設(shè)置。通過在任務(wù)中調(diào)用osal_start_timer函數(shù)設(shè)置時間標志位。如果指明任務(wù)ID，則可以用osal_start_timerEx()函數(shù)替代osal_start_timer().
原型:
byte osal_start_timer(UINT16 event_id, UINT16 timeout_value);
參數(shù)：
event_id : 用戶定義的事件標志位event bit. 當定時器到點時，事件將通知任務(wù)。
timeout_value ：定時值（ms）
返回值：
ZSUCCESS Timer 成功開啟
NO_TIMER_AVAILABLE 無法開啟
（2） osal_start_timerEx( )
功能描述：
功能與osal_start_timer()相近，只不過參數(shù)多了一個任務(wù)ID，這個函數(shù)允許調(diào)用者為另一個任務(wù)啟動定時器
原型：
byte osal_start_timerEx( byte taskID, UINT16 event_id, UINT16
timeout_value);
參數(shù)：
參數(shù)1：taskID 當定時器終止時，得到該事件的任務(wù)ID
參數(shù)2：event_id,是用戶定義的事件位，當定時器終止時，正在調(diào)用的任務(wù)將被通報
參數(shù)3：定時器事件被設(shè)置之前時間的計數(shù)
返回值：
ZSUCCESS Timer 成功開啟
NO_TIMER_AVAILABLE 無法開啟
（3）osal_stop_timer( )
功能描述：
停止正在運行的定時器，停止外部事件調(diào)用osal_stop_timerEx()，可以停止不同任務(wù)的定時器。
原型：
byte osal_stop_timer( UINT16 event_id );
參數(shù)：
event_id ：將要結(jié)束的目標事件（該事件是啟動定時器的事件）定時器的標識符
返回值：
ZSUCCESS Timer 成功停止
INVALID_EVENT_ID 無效事件
（4）osal_stop_timerEx( )
功能描述：
結(jié)束外部事件的定時器，指明了任務(wù)的ID
原型：
byte osal_stop_timerEx( byte task_id, UINT16 event_id );
參數(shù)：
參數(shù)1：停止定時器所在的任務(wù)ID
參數(shù)2：被停止定時器的標識符
返回值
ZSUCCESS Timer 成功停止
INVALID_EVENT_ID 無效事件
（5）osal_GetSystemClock( )
功能描述：
讀取系統(tǒng)時間
原型：
uint32 osal_GetSystemClock( void );
參數(shù)：
無
返回值：
系統(tǒng)時間（ms）
4 中斷管理API
這些API實現(xiàn)任務(wù)與外部中斷的接口，函數(shù)允許一個任務(wù)關(guān)聯(lián)每一個具體的中斷程序程序，可以開關(guān)中斷。在中斷服務(wù)程序內(nèi)，其他任務(wù)可以設(shè)置事件。
（１） osal_int_enable( )
功能描述：
函數(shù)用于使能中斷。一旦允許中斷發(fā)生將引起中斷分配的服務(wù)程序運行。
原型：
byte osal_int_enable( byte interrupt_id )
參數(shù)：
interrupt_id ：被允許的中斷的標識符。
返回值：
ZSUCCESS Interrupt 成功使能
INVALID_INTERRUPT_ID 無效中斷
（2）osal_int_disable( )
功能描述：
關(guān)閉中斷
原型：
byte osal_int_disable( byte interrupt_id )
參數(shù)：
被禁止中斷的標識符
返回值：
ZSUCCESS Interrupt 成功關(guān)閉
INVALID_INTERRUPT_ID 無效中斷
5 任務(wù)管理API
該API用在添加和管理OSAL中的任務(wù)。每一個任務(wù)由任務(wù)初始化函數(shù)和時間處理函數(shù)組成。
（1）osal_init_system()
功能描述：
該函數(shù)初始化OSAL系統(tǒng)。該函數(shù)必須在啟動任何一個OSAL函數(shù)之前被調(diào)用
原型：
byte osal_init_system( void )
參數(shù):
無
返回值：
ZSUCCESS 成功
（2）osal_start_system()
功能描述：
這個函數(shù)是系統(tǒng)任務(wù)的主循環(huán)函數(shù)，在循環(huán)里面將遍歷所有的任務(wù)事件，為觸發(fā)事件的任務(wù)調(diào)用任務(wù)事件處理函數(shù)。如果一個特定任務(wù)有事件發(fā)送，那么該函數(shù)就將調(diào)用該任務(wù)的事件處理函數(shù)。當事件處理完之后，將返回主循環(huán)。繼續(xù)查找其他的任務(wù)事件。如果沒有事件，函數(shù)將把處理器轉(zhuǎn)到睡眠模式。
原型：
void osal_start_system( void )
參數(shù)：
無
返回值：
無
（3）osal_self( )
功能描述：
這個函數(shù) 返回正在被調(diào)用任務(wù)的任務(wù)標識符。如果在一個中斷服務(wù)子程序中調(diào)用該函數(shù)將返回一個錯誤結(jié)果。
函數(shù)原型
byte osal_self( void )
參數(shù)描述
無
返回值：
返回值為當前活動的任務(wù)的任務(wù)標識符
（4）osalTaskAdd( )
功能描述：
這個函數(shù)添加一個任務(wù)到任務(wù)系統(tǒng)中，一個任務(wù)由兩個函數(shù)組成 – 初始化與信息處理。信息處
理函數(shù)在事件時發(fā)生，而后處理其中之一，并返回其余到主循環(huán)中。
函數(shù)原型
//任務(wù)初始化函數(shù)原型
typedef void(*pTaskInitFn) (unsigned char task_id);
//事件句柄函數(shù)原型
typedef unsigned short (*pTaskEventHandlerFn)(unsigned char task_id,unsigned short event);
//添加任務(wù)函數(shù)原型
void osalTaskAdd(const pTaskInitFn pfnInit,const pTaskEventHandlerFn,pfnEventProcessor,
const byte taskPriority);
參數(shù)描述
pfnInit – 指向任務(wù)初始化函數(shù)的指針
pfnEventProcessor – 指向任務(wù)事件處理器函數(shù)的指針
taskPriority – 任務(wù)的優(yōu)先級。值為 0 ~ 255 之間
優(yōu)先級 值
OSAL_TASK_PRIORITY_LOW 50
OSAL_TASK_PRIORITY_MED 130
OSAL_TASK_PRIORITY_HIGH 230
6 內(nèi)存管理API
該 API 呈現(xiàn)一個簡單的內(nèi)存分配系統(tǒng)。這些函數(shù)允許動態(tài)內(nèi)存分配。
（1）osal_mem_alloc( )
功能描述：
這個函數(shù)是一個簡單內(nèi)存分配函數(shù)，如果成功則返回一個緩沖區(qū)的指針。
函數(shù)原型
oid *osal_mem_alloc(uint16 size);
參數(shù)描述
ize – 緩沖區(qū)的大小
返回值
一個 void 指針指向新分配的緩沖區(qū)，如果沒有足夠的內(nèi)存來分配，則返回一個 NULL 指針。
（3） osal_mem_free
功能描述：
這個函數(shù)釋放已分配的內(nèi)存來重新使用。只有當內(nèi)存已使用 osal_mem_alloc( )分配過才可以工作。
函數(shù)原型
oid osal_mem_free(void *ptr);
參數(shù)描述
ptr - 指向?qū)⒈会尫诺木彌_區(qū)的指針，這個緩沖區(qū)之前必須被 osal_mem_alloc( )分配過使用。
返回值
無。
7. 電源管理 API
這里的函數(shù)描述了OSAL的電源管理系統(tǒng)，當OSAL安全的關(guān)閉接收器宇外部硬件并使處理器進入休眠模式時，該系統(tǒng)提供想應(yīng)用/任務(wù)通報該事件的方法
（1） osal_pwrmgr_task_state( )
功能描述：
該函數(shù)被每個任務(wù)調(diào)用，聲明該任務(wù)是否需要節(jié)能，任務(wù)被創(chuàng)建時，默認是節(jié)能模式。如果任務(wù)總是需要節(jié)能，那么就不需要調(diào)用該函數(shù)。
函數(shù)原型
byte osal_pwrmgr_task_state(byte task_id,pwrmgr_state_t state);
參數(shù)描述
state – 改變一任務(wù)電源狀態(tài)。
類型 描述
PWRMGR_CONSERVE 打開節(jié)能模式，所有任務(wù)都須一致，為任務(wù)初始化的缺省模式。
PWRMGR_HOLD 關(guān)閉節(jié)能模式
返回值
返回值顯示操作的結(jié)果。
返回值 描述
ZSUCCESS 成功
INVALID_TASK 無效任務(wù)
(2) osal_pwrmgr_device()
功能描述：
該函數(shù)在上電或電源需求變更時調(diào)用（例如電源支持協(xié)調(diào)器）。這一函數(shù)設(shè)置了大體的設(shè)備電源管理的開/關(guān)狀態(tài)。該函數(shù)應(yīng)當從中央控制實體（如ZDO)被調(diào)用。
原型：
void osal_pwrmgr_state( byte pwrmgr_device );
參數(shù)：
pwrmgr_device ：更改或設(shè)置節(jié)電模式
PWRMGR_ALWAYS_ON 無節(jié)電
PWRMGR_BATTERY 開節(jié)電
返回值：
無
8．非易失性（NV）存儲管理
這部分講述 OSAL NV非易失性（NV）存儲系統(tǒng)。系統(tǒng)提供了一種方式來為應(yīng)用永久存放信息到設(shè)備內(nèi)存中。
他也可以用于某些堆棧條目的固定存儲，這些 NV函數(shù)被設(shè)計用來讀取/寫入用戶定義的由任何數(shù)據(jù)類型組成的(如結(jié)構(gòu)與數(shù)組)項目。用戶可以通過設(shè)定一適當?shù)钠屏颗c長度讀取或?qū)懭胍粋�完整的項目或項目中的一個單元。 該API為NV存儲介質(zhì)獨有，與存儲體本身沒有關(guān)系�？梢员籪lash或eeprom使用。
每個 NV 項目都有一個惟一的標識符，每個應(yīng)用都有特定的 ID值范圍(其余 ID值為保留，或為棧、平臺所用)。如果你的應(yīng)用創(chuàng)建了自己的 NV項目，則必須從應(yīng)用值范圍內(nèi)選一個 ID。如下
0x0000 Reserved
0x0001 – 0x0020 OSAL
0x0021 – 0x0040 NWK
0x0041 – 0x0060 APS
0x0061 – 0x0080 Security
0x0081 – 0x00A0 ZDO
0x00A1 – 0x0200 Reserved
0x0201 – 0x0FFF Application
0x1000 -0xFFFF Reserved
在使用API時有一些重要的注意點：
1)這些是模塊化函數(shù)調(diào)用，一個操作需要花費幾毫秒來完成，特別是 NV寫操作。另外，中斷
需求禁止幾毫秒。最好是在與其他時間性操作上沒有沖突的時刻來執(zhí)行這些函數(shù)。例如，一
個較佳的寫 NV 項目時刻是接收器關(guān)閉的時候。
2) 不要經(jīng)常性寫 NV，它需要花費時間與能源，并且大多數(shù)的閃存都有一個最大擦除次數(shù)限制。
3) 如果一個或多個 NV 項目變更，特別是 Z-stack的版本升級，它必須擦除且重新初始化 NV
內(nèi)存。否則，讀與寫已變更的 NV項目操作將失敗或產(chǎn)生錯誤的結(jié)果。
(1) osal_nv_item_init( )
功能描述：
初始化 NV中的一條項目。這個函數(shù)檢測 NV項目的存在，如果不存在，則它用
數(shù)據(jù)創(chuàng)建與初始化一個 NV 項目，如果有的話。 在調(diào)用 osal_nv_read( )或osal_nv_write( )前，每一個項目必須先調(diào)用該函數(shù)。
函數(shù)原型
yte osal_nv_item_init(uint16 id,uint16 len,void *buf);
參數(shù)描述
id – 用戶定義項目標識符
len – 項目長度(字節(jié))
buf – 項目初始化數(shù)據(jù)指針，如果沒有初始化數(shù)據(jù)，則設(shè)為 NULL.
返回值
返回值顯示操作的結(jié)果。
返回值 描述
ZSUCCESS 成功
NV_ITEM_UNINIT 成功但項目不存在
(2) osal_nv_read( )
功能描述：
讀取 NV數(shù)據(jù)，這個函數(shù)被用來讀取整個 NV項目或一個項目中項目，讀取的數(shù)據(jù)被復(fù)制到*buf 中。
函數(shù)原型
yte osal_nv_read( uint16 id, uint16 offset, uint16 len, void *buf);
參數(shù)描述
d – 用戶定義項目標識符
ffset – 項目的內(nèi)存偏移量(字節(jié))
en – 項目長度(字節(jié))
buf – 數(shù)據(jù)讀取到該緩沖區(qū)
返回值
返回值顯示操作的結(jié)果。
返回值 描述
ZSUCCESS 成功
NV_ITEM_UNINIT 項目沒有初始化
NV_OPER_FAILED 操作失敗
（2） nv_osal_write( )
功能描述：
寫入數(shù)據(jù)到 NV中，這個函數(shù)被用來寫入整個 NV項目或一個項目中的單元(通過一個偏移量來索
引該項目)。
函數(shù)原型
byte osal_nv_write( uint16 id,uint16 offset,uint16 len,void *buf);
參數(shù)描述
id – 用戶定義項目標識符
offset – 項目的內(nèi)存偏移量(字節(jié))
len – 項目長度(字節(jié))
*buf – 要寫入的數(shù)據(jù)
返回值
返回值顯示操作的結(jié)果。
返回值 描述
ZSUCCESS 成功
NV_ITEM_UNINIT 項目沒有初始化
NV_OPER_FAILED 操作失敗
（3） osal_offsetof( )
功能描述：
該宏在一個結(jié)構(gòu)中按字節(jié)計算一個單元的內(nèi)存偏移量，它被 NV API 函數(shù)用來計算偏移量。
函數(shù)原型
sal_offsetof(type,member)
參數(shù)描述
ype – 結(jié)構(gòu)類型
member – 結(jié)構(gòu)成員
|
