ZigBee操作系统抽象层应用程序编程接口.pdf

《ZigBee操作系统抽象层应用程序编程接口.pdf》由会员分享，可在线阅读，更多相关《ZigBee操作系统抽象层应用程序编程接口.pdf（25页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究Z-StackZ-StackZ-StackZ-Stack 操作系统抽象层操作系统抽象层操作系统抽象层操作系统抽象层应用程序编程接口应用程序编程接口应用程序编程接口应用程序编程接口文件编号：F8W-2003-0002德州仪器股份有限公司美国加利福尼亚州圣迭戈(619)497-3845郑州新双恒郑州新双恒(www.zigbee-

2、www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究i版本版本描述描述日期日期1.0最初发行的ZigBee1.0版本。04/08/20051.1增加了个域网内存API说明中个域网初始化的注释。07/22/20051.2修改了事物管理API 的讨论研究。08/25/20051.3改变了标题页的标志,改变了页脚的版权。02/27/20061.4修改了电源管理的 API。11/27/20061.5弃用了osal_self()

3、和 osalTaskAdd()。12/18/2007郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究目录1、引言.61.1目地.61.2范围.61.3简称.62、API 概述.72.1概述.73、信息管理 API.83.1 介绍.83.2osal_msg_allocate().83.2.1函数描述.83.2.2函数原形.83.2.3参数描述.83.2.4返回值.83.3o

4、sal_msg_deallocate().83.3.1函数描述.83.3.2函数原型.83.3.3参数描述.83.3.4返回值.83.4osal_msg_send().93.4.1函数描述.93.4.2函数原型.93.4.3参数描述.93.4.4返回值.93.5 osal_msg_receive().103.5.1函数描述.103.5.2函数原型.103.5.3参数描述.103.5.4返回值.104、任务同步 API.114.1介绍.114.2osal_set_event().114.2.1函数描述.114.2.2函数原型.114.2.3参数描述.114.2.4返回值.115、定时器管理 AP

5、I.125.1介绍.125.2osal_start_timer().125.2.1函数描述.125.2.2函数原型.125.2.3参数描述.125.2.4返回值.125.3osal_start_timerEx().135.3.1函数描述.135.3.2函数原型.135.3.3参数描述.135.3.4返回值.135.4osal_stop_timer().13郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 20

6、05-2007版权所有 违者必究5.4.1函数描述.135.4.2函数原型.135.4.3参数描述.135.4.4返回值.145.5osal_stop_timerEx().145.5.1函数描述.145.5.2函数原型.145.5.3参数描述.145.5.4返回值.145.6osal_GetSystemClock().145.6.1函数描述.145.6.2函数原型.145.6.3参数描述.145.6.4返回值.156、中断管理 API.166.1介绍.166.2osal_int_enable().166.2.1函数描述.166.2.2函数原型.166.2.3参数描述.166.2.4返回值.16

7、6.3osal_int_disable().166.3.1函数描述.166.3.2函数原型.166.3.3参数描述.166.3.4返回值.177、任务管理 API.187.1介绍.187.2osal_init_system().187.2.1函数描述.187.2.2函数原型.187.2.3参数描述.197.2.4返回值.197.3osal_start_system().197.3.1函数描述.197.3.2函数原型.197.3.3参数描述.197.3.4返回值.197.4osal_self().197.4.1函数描述.197.5osalTaskAdd().197.5.1函数描述.198、内存管

8、理 API.208.1介绍.208.2osal_mem_alloc().208.2.1函数描述.208.2.2函数原型.208.2.3函数描述.208.2.4返回值.208.3osal_mem_free().20郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究8.3.1函数描述.208.3.2函数原型.208.3.3参数描述.208.3.4返回值.209、电源管理 API

9、.219.1介绍.219.2osal_pwrmgr_device().219.2.1函数描述.219.2.2函数原型.219.2.3参数描述.219.2.4返回值.219.3osal_pwrmgr_task_state().219.3.1函数描述.229.3.2函数原型.229.3.3参数描述.229.3.4返回值.2210、非易失性存储器的 API.2310.1介绍.2310.2osal_nv_item_init().2310.2.1函数描述.2310.2.2函数原型.2410.2.3参数描述.2410.2.4返回值.2410.3osal_nv_read().2410.3.1函数描述.241

10、0.3.2函数原型.2410.3.3参数描述.2410.3.4返回值.2410.4osal_nv_write().2510.4.1函数描述.2510.4.2函数原型.2510.4.3参数描述.2510.4.4返回值.2510.5osal_offsetof().2510.5.1函数描述.2510.5.2函数原型.2510.5.3参数描述.25iv郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-200

11、7版权所有 违者必究1、引言1.1目地文件的目地是规定操作系统抽象层的API。这个API允许Z-stack中的软件组件的要点或任务环境(包括操纵系统或连接到中断系统)被写入独立于特定的操作系统中。该OSAL是被执行的目标。1.2范围文件中列举了通过OSAL提供所有调用函数。函数调用中细节给予充分的详述便于程序员去实现它们。1.3简称API应用程序编程接口OSAL操作系统抽象层PC个人电脑SPI串行端口接口1郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-00

12、02 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究2、API 概述2.1概述操作系统抽象层通过特定的操作环境常用于屏蔽软件组成中的（Z-stack）。在一定程序上它提供了与操作环境无关的下述功能。1、任务记录，初始化，启动2、任务之间的信息交换3、任务同步4、中断处理5、定时器6、内存分配2郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究

13、3、信息管理 API3.1介绍信息管理 API 为任务和处理单元之间的信息交换提供了一种具有不同处理环境的机制（例如，在一个控制循环中调用中断服务常规程序或函数）。这个 API 中的函数可以使任务分配或回收信息缓冲区，给其它任务发送命令信息以及接收回复信息。3.2osal_msg_allocate()3.2.1函数描述这个函数被一个任务调用去分配一个信息缓冲，这个任务/函数将填充这信息并且调用osal_msg_send()发送信息到另一个任务中。假如缓冲器不能被分配，msg_ptr 将设置为空。注明：不能把这个函数和 osal_mem_alloc()混淆，这个函数用来分配缓冲区以在任务之间发送

14、信息（使用）osal_msg_send()任务中，运用 osal_mem_alloc()分配块存储。3.2.2函数原形byte*osal_msg_allocate(uint16len)3.2.3参数描述len 是信息的长度。3.2.4返回值这返回值是指向一个信息分配的缓冲区的指针。一个空值的返回标明了信息分配操作失败。3.3osal_msg_deallocate()3.3.1函数描述这个函数用来回收一个信息缓冲区。在完成处理一个接收信息后这个函数被一个任务(或处理机单元)调用。3.3.2函数原型byteosal_msg_deallocate(byte*msg_ptr)3.3.3参数描述msg_

15、ptr 是指向必须被回收的信息缓冲的指针。3.3.4返回值返回值指示了操作的结果。3郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究3.4osal_msg_send()3.4.1函数描述osal_msg_send()函数被一个任务调用来给另一个任务或处理单元发送命令或数据信息。标识符的 destination_task 字段必须提到一个有效的系统任务。当调用 osal_c

16、reate_task()来启动一个任务时，任务标识符被分配。osal_msg_send()函数也将设置目标任务事件列表中的SYS_EVENT_MSG 事件。3.4.2函数原型byteosal_msg_send(bytedestination_task,byte*msg_ptr)3.4.3参数描述destination_task 是接收信息的任务的 ID。msg_ptr 是指向包含信息的缓冲区的指针。msg_ptr 必须指向 osal_msg_allocate()分配的一个有效缓冲区。3.4.4返回值返回值是一个字节，表明操作结果。4返回值描述ZSUCCESS分配成功INVALID_MSG_PO

17、INTER无效的信息指针MSG_BUFFER_NOT_AVAIL缓冲区队列返回值描述ZSUCCESS信息发送成功INVALID_MSG_POINTER无效的信息指针INVALID_TASKDestination_task 是无效的郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究3.5osal_msg_receive()3.5.1函数描述这个函数被一个任务调用来检索一条已收

18、到的命令信息。调用 osal_msg_deallocate()处理信息之后，调用任务必须回收信息缓冲区）。3.5.2函数原型byte*osal_msg_receive(bytetask_id)3.5.3参数描述task_id 是调用任务（信息指定的）的标识符。3.5.4返回值返回值是一个指向包含该信息的缓冲区的指针，如果没有已接收的信息为空。5郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-200

19、7版权所有 违者必究4、任务同步 API4.1介绍这个 API 使得任务等待事件发生，并在等待期间返回控制。这个 API 中的函数可以用来为一个任务设置事件，并无论设置了什么事件都通知任务。4.2osal_set_event()4.2.1函数描述通过这个函数调用为一个任务设置事件标志。4.2.2函数原型byteosal_set_event(bytetask_id,UINT16event_flag)4.2.3参数描述task_id 是要设置事件的任务的标识符。event_flag 是两个字节的位图且每个位详述了一个事件。这仅有一个系统事件(SYS_EVENT_MSG)，其余的事件/位是通过接收任

20、务来规定的。4.2.4返回值返回值指示了操作的结果。6返回值描述ZSUCCESS成功INVALID_TASK无效的事件郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究5、定时器管理 API5.1介绍这个 API 使得内部的（Z-Stack）任务和外部的（应用层）任务都可以使用定时器。API提供了启动和停止一个定时器的功能，这定时器可设定递增的一毫秒。5.2osal_sta

21、rt_timer()5.2.1函数描述启动一个定时器时调用此函数。当定时器终止，这给定的事件的位将设置。这个事件通过osal_start_timer 函数调用将在任务中设置。要明确指定这任务的标识符，运用osal_start_timerEx()而不是 osal_start_timer()。5.2.2函数原型byteosal_start_timer(UINT16event_id,UINT16timeout_value);5.2.3参数描述event_id 是用户确定事件的位。当定时器终止时，调用任务将被告知（该事件）。timeout_value 指定时器事件设置之前的时长（以毫秒为单位）。5.2

22、.4返回值返回值指示了操作的结果。7返回值描述ZSUCCESS定时器启动成功NO_TIMER_AVAILABLE没有能够启动定时器郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究5.3osal_start_timerEx()5.3.1函数描述这类似于 osal_start_timer()，增加了 taskID 参数。它允许访问者调用程序为另一个任务设置定时器。当存在疑问时

23、，运用 osal_start_timer()之上的函数。5.3.2函数原型byteosal_start_timerEx(bytetaskID,UINT16event_id,UINT16timeout_value);5.3.3参数描述taskID 是当定时器终止时，获得该事件任务的 ID。event_id 是用户确定事件的位。当定时器终止，调用任务将被告知（该事件）。timeout_value 是定时器事件设置之前的时长（以毫秒为单位）。5.3.4返回值返回值指出了操作的结果。.5.4osal_stop_timer()5.4.1函数描述调用函数用来停止一个已启动的定时器。假如成功的话，这函数将取

24、消定时器并阻止设置调用程序中与定时器相关的事件。使用 osal_stop_timer()函数 意味着在调用osal_stop_timer()的任务中的计时器正在运行。为了在不同的任务中中止定时器，运用osal_stop_timerEx()而不是 osal_stop_timer()。5.4.2函数原型byteosal_stop_timer(UINT16event_id);5.4.3参数描述event_id指要停止的计时器的标识符。8返回值描述ZSUCCESS定时器启动成功NO_TIMER_AVAILABLE没有能够启动定时器郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www

25、.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究5.4.4返回值返回指示操作结果的值。5.5osal_stop_timerEx()5.5.1函数描述这个函数和 osal_stop_timer 相似，例外的是在调用 osal_stop_timerEx 时 task_id 被指定。5.5.2函数原型byteosal_stop_timerEx(bytetask_id,UINT16event_id);5.5.3参数描述task_id 是停止计时器的任

26、务。event_id 被停止的定时器的标识符。5.5.4返回值返回值表明操作结果。5.6osal_GetSystemClock()5.6.1函数描述调用此函数读取系统时钟。5.6.2函数原型uint32osal_GetSystemClock(void);5.6.3参数描述无。9返回值描述ZSUCCESS关闭定时器成功INVALID_EVENT_ID无效事件返回值描述ZSUCCESS关闭定时器成功INVALID_EVENT_ID无效事件郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(A

27、PI)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究5.6.4返回值系统时钟，以毫秒为单位。10郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究6、中断管理 API6.1介绍此 API 使得一个任务可以与外部中断相互交流。API 中的函数允许和每个中断去联络一个具体的服务例程。中断可以启用或禁用。在服务例程内部，

28、可以为其它任务设置事件。6.2osal_int_enable()6.2.1函数描述调用此函数启用一个中断。一旦启用，中断发生将引起与该中断相联系的服务例程的调用。6.2.2函数原型byteosal_int_enable(byteinterrupt_id)6.2.3参数描述interrupt_id 识别有效的中断字符。指明要启用的中断。6.2.4返回值返回值指示操作结果。6.3osal_int_disable()6.3.1函数描述调用此函数禁用一个中断。当禁用一个中断时，与该中断相联系的服务例程不被调用。6.3.2函数原型byteosal_int_disable(byteinterrupt_id

29、)6.3.3参数描述interrupt_id 识别无效的中断字符。指明要禁用的中断。11返回值描述ZSUCCESS开启中断成功INVALID_INTERRUPT_ID无效中断郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究6.3.4返回值返回值指明操作结果。12返回值描述ZSUCCESS关闭中断成功INVALID_INTERRUPT_ID无效中断郑州新双恒郑州新双恒(ww

30、w.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究7、任务管理 API7.1介绍在 OSAL 系统中，API 常用于添加和管理任务。每个任务由初始化函数和事件处理函数组成。OSAL 调用 osalInitTasks()(应用程序提供)去初始化这任务且 OSAL 运用一个任务列表(constpTaskEventHandlerFntasksArr)去为每个任务(也是应用程序提供)调用事件处理程序。执行任

31、务列表的例子：constpTaskEventHandlerFntasksArr=macEventLoop,nwk_event_loop,Hal_ProcessEvent,MT_ProcessEvent,APS_event_loop,ZDApp_event_loop,;constuint8tasksCnt=sizeof(tasksArr)/sizeof(tasksArr0);执行osalInitTasks()的例子：voidosalInitTasks(void)uint8taskID=0;tasksEvents=(uint16*)osal_mem_alloc(sizeof(uint16)*tas

32、ksCnt);osal_memset(tasksEvents,0,(sizeof(uint16)*tasksCnt);macTaskInit(taskID+);nwk_init(taskID+);Hal_Init(taskID+);MT_TaskInit(taskID+);APS_Init(taskID+);ZDApp_Init(taskID+);7.2osal_init_system()7.2.1函数描述这函数初始化 OSAL 系统。在使用任何其它 OSAL 函数之前必须先调用此函数启动OSAL 系统。7.2.2函数原型byteosal_init_system(void)13郑州新双恒郑州新

33、双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究7.2.3参数描述无。7.2.4返回值指明操作结果。7.3osal_start_system()7.3.1函数描述这个函数是任务系统中的主循环函数。它将仔细检查所有的任务事件且且为含有该事件的任务调用任务事件处理函数。假如这有特定任务的事件，这个函数将为该任务调用事件处理例程来处理事件。相应任务的事件处理例程一次处理一个事件。一个事件被服务

34、后，剩余的事件将等待下一次循环。如果这没有事件(服务与所有任务)，这个函数使处理器程序处于睡眼模式。7.3.2函数原型byteosal_init_system(void)7.3.3参数描述无。7.3.4返回值返回指示操作结果的值。7.4osal_self()7.4.1函数描述这一函数已被淘汰并不再支持。7.5osalTaskAdd()7.5.1函数描述这个函数已被淘汰且不被支持。关于OSAL任务初始化和事件处理参考7.1节。14返回值描述ZSUCCESS成功郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSA

35、L 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究8、内存管理 API8.1介绍该API 代表一个简单的内存分配系统。这些函数允许动态存储内存分配。8.2osal_mem_alloc()8.2.1函数描述这个函数是一个简单的内存分配函数，返回一个指向缓冲区的指针（如果成功）。8.2.2函数原型void*osal_mem_alloc(uint16size);8.2.3函数描述size要求的缓冲区的字节数值。8.2.4返回值指向新分配的缓冲区的空指针（应指向目的缓冲类型）。如果没有足够的内存可分配，一个返回NUL

36、L指针。8.3osal_mem_free()8.3.1函数描述此函数释放存储空间便于再次运用。仅在内存已经通过调用osal_mem_alloc()被分配才有效。8.3.2函数原型voidosal_mem_free(void*ptr);8.3.3参数描述ptr指向要释放的缓冲区的指针。这个缓冲区必须之前通过调用osal_mem_alloc()已被分配。以前分配过的空间。8.3.4返回值无。15郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.

37、5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究9、电源管理 API9.1介绍这章节描述OSAL的电源管理系统。当它安全关闭接收器和外部硬件时，这个系统为应用程序或任务提供了一种告知OSAL的方法。接着使处理器转入睡眠。有2个函数控制电源管理。第一个，调用osal_pwrmgr_device()去设置设备的级别模式(省电或不省电)。接着，有一个任务电源状态，通过调用osal_pwrmgr_task_state(PWRMGR_HOLD)，每个任务可以在节电模式中推迟电源管理。假如一个任务保持电源管理，它将必须调用osal_pwrmgr_task_state(PWRMGR_CO

38、NSERVE)，允许在节电模式中继续使用电源管理。默认情况下，当任务已初始化，每个任务的能源状态设置成PWRMGR_CONSERVE,保护电池的管理软件。因此这个任务不想推迟电源保护，它就不必调用osal_pwrmgr_task_state()。在进入电源保护状态之前，电源管理将查看设备模式，以及所有任务的集体电源状态。9.2osal_pwrmgr_device()9.2.1函数描述当升高电源或需要改变电源时（例如，电池支持的协调器）这个函数应由中心控制实体（比如ZDO）调用。9.2.2函数原型voidosal_pwrmgr_state(bytepwrmgr_device);9.2.3参数描述

39、pwrmgr_device改变和设置电源的节省模式。9.2.4返回值无。16类型描述PWRMGR_ALWAYS_ON这一选项没有省电模式，设备很可能使用主电源供电。PWRMGR_BATTERY打开省电模式郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究9.3osal_pwrmgr_task_state()9.3.1函数描述无论这个任务是否想要保护电源，每个任务都将调用此函

40、数。任务将调用此函数来表决是否需要OSAL保护电源或推迟电源保护。默认情况下，当一个任务被创建时，它自己的电源状态设置为保护模式。如果该任务一直想要保护电源，就根本不必调用此函数。9.3.2函数原型byteosal_pwrmgr_task_state(bytetask_id,bytestate);9.3.3参数描述state改变一个任务的电源状态。9.3.4返回值返回标示操作状态的值。17标志描述PWRMGR_CONSERVE打开省电模式,所有事件必须允许。事件初始化时这是默认状态。PWRMGR_HOLD关闭省电模式返回值描述ZSUCCESS成功INVALID_TASK无效事件郑州新双恒郑州新

41、双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究10、非易失性存储器的 API10.1介绍这一节描述了OSAL非易失性存储器系统。该系统为应用程序提供了一种把信息永久保存到设备内存的方法。它还能用于ZigBee规范要求的把某些项目永久保存到协议栈。NV函数的职能是读写任意数据类型的用户自定义项目，比如结构体和数组。用户能通过设置适当的偏移和长度来读和写一个整体的项目或元素。API独立于N

42、V存储介质，并且能用于实现闪存或EEPROM。每个易失性的项目都仅有一个ID，当一些ID值由栈或平台保留或运用时，应用程序中有特定一系列的ID值。假如应用程序创建自己的易失性项目，它必须从应用范围的值内选择一个标识符。参考下面的列表：运用API时一些重要的注意事项：1、有一些模块化调用函数，操作系统可能需要几毫秒来完成。对于NV写入操作尤其是这样。另外，中断可能禁用几个毫秒。当他们不与时序要求较严格的操作发生冲突时，最好间或执行这些函数。例如，当接受器被关掉时正是写NV 项目的好时间。2、尽量不要太频繁的执行NV写入操作。它需要时间和能源，而且闪存设备有一个有限的擦除周期数。3、假如结构体中一

43、个多个NV项目改变，尤其是从一个Z-Stack版本升级到另一个时，必须擦除和重新初始化NV内存。否则，修改NV项目的读写操作将失败，或产生错误结果。10.2osal_nv_item_init()10.2.1函数描述初始化NV项目，这个函数检查存在NV的项目，假如不存在，它将通过这个函数去创建或初始化。假如真存在的话，在调用osal_nv_read()或osal_nv_write()之前，每个项目都应调用此函数。18值使用者0 x0000保留0 x0001 0 x0020操作系统抽象层0 x0021 0 x0040网络层0 x0041 0 x0060应用支持子层0 x0061 0 x0080安全

44、0 x0081 0 x00A0Zigbee设备对象0 x00A1 0 x0200保留0 x0201 0 x0FFF应用程序0 x1000-0 xFFFF保留郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究10.2.2函数原型byteosal_nv_item_init(uint16id,uint16len,void*buf);10.2.3参数描述id用户自定义项的ID。le

45、n项目字节长度。*buf初始化数据的指针。如没初始化数据，则设置为空。10.2.4返回值返回指示操作结果的值。10.3osal_nv_read()10.3.1函数描述从NV中读出数据。这个函数能用来从NV 中带有偏移的索引指向的项目读出整个项目或一个元素。读出的数据复制到*buf中。10.3.2函数原型byteosal_nv_read(uint16id,uint16offset,uint16len,void*buf);10.3.3参数描述id用户自定义项的IDoffset以字节为单位到项目的存储偏移量。len项目长度以字节为单位。*buf数据读取到缓冲区10.3.4返回值指示返回操作结果的值。

46、19返回值描述ZSUCCESS成功NV_ITEM_UNINIT成功但对象不存在NV_OPER_FAILED操作失败返回值描述ZSUCCESS成功NV_ITEM_UNINIT对象没有初始化NV_OPER_FAILED操作失败郑州新双恒郑州新双恒(www.zigbee-www.zigbee-www.zigbee-www.zigbee-)译译Z-Stack OSAL 应用程序编程接口(API)F8W-2003-0002 版本 1.5版权德州仪器股份有限公司公司 2005-2007版权所有 违者必究10.4osal_nv_write()10.4.1函数描述写入数据到NV，这个函数用来通过带有偏移的索引

47、指向项目的偏移量来写入整个NV项目。项目的元素。10.4.2函数原型byteosal_nv_write(uint16id,uint16offset,uint16len,void*buf);10.4.3参数描述id用户自定义ID。offset以字节为单位到项目的存储偏移量。len项目长度以字节为单位。*buf-数据写入到缓冲区。10.4.4返回值返回指定操作结果的值。10.5osal_offsetof()10.5.1函数描述这个宏计算一个结构体内元素的内存偏移量，以字节为单位。用它来计算NV API函数使用的参数的偏移量是有用的。10.5.2函数原型osal_offsetof(type,member)10.5.3参数描述type结构体类型。member结构体成员。20返回值描述ZSUCCESS成功NV_ITEM_UNINIT对象未初始化NV_OPER_FAILED操作失败