1、Zigbee 协议栈 OSAL 层 API 函数 (2010-11-19 21:18) 分类： ZigBee 技术学习 OSAL 层提供了很多的 API 来对整个的协议栈进行管理。主要有下面的几类：信息管理、任务同步、时间管理、中断管理、任务管理、内存管理、电源管理以及非易失存储管理。看到这些管理是不是感觉越来越像一个操作系统了。1. 信息管理 API信息管理为任务间的信息交换或者外部处理事件（例如：中断服务程序或一个控制循环内的函数调用）提供一种管理机制。包括允许任务分配或不分配信息缓存、发送命令信息到其他任务、接受应答信息等 API 函数。（1)osal_msg_allocate ( )功
2、能描述： 为信息分配缓存空间、任务调用或函数被调用的时候，该空间被信息填充或调用发送信息函数 osal_msg_send()发送缓存空间的信息到其他任务。原型：byte *osal_msg_allocate( uint16 len )参数：len ：消息的长度返回值：指向消息缓冲区的指针，当分配失败时返回 NULL注意：不能与函数 osal_mem_alloc()混淆，osal_mem_alloc()函数被用于为在任务间发送信息分配缓冲区，用该函数也可以分配一个存储区。（2）osal_msg_deallocate( )功能描述：用于收回缓冲区原型：byte osal_msg_deallocat
3、e( byte *msg_ptr )参数：Msg_ptr : 指向将要收回的缓冲区的指针返回值：ZSUCCESS 回收成功INVALID_MSG_POINTER 错误的指针MSG_BUFFER_NOT_AVAIL 缓冲区在队列中（3） osal_msg_send( )功能描述：任务调用这个函数以实现发送指令或数据给另一个任务或处理单元。目标任务的标识必须是一个有效的系统任务，当调用 osal_create_task ( )启动一个任务时，将会分配任务标识。osal_msg_send()也将在目标任务的事件列表中设置 SYS_EVENT_MSG原型：byte osal_msg_send( byt
4、e destination_task, byte *msg_ptr )参数：destination_task ：目标任务的标识msg_ptr ： 指向消息缓冲区的指针，必须是 osal_msg_allocate ( )函数分配的有效的数据缓存返回值：返回一个字节，指示操作的结果.ZSUCCESS 消息发送成功INVALID_MSG_POINTER 无效指针INVALID_TASK 目标任务无效(4) osal_msg_receive( )功能描述：任务调用这个函数来接收消息。消息处理完毕后，发送消息的任务必须调用osal_msg_deallocate()收回缓冲区。一个任务接收一个命令信息是，
5、调用该函数原型：byte *osal_msg_receive( byte task_id )参数：task_id ：消息发送者的任务标识返回值：指向消息所存放的缓冲区指针，如果没有收到消息将返回 NULL。2 同步任务 API这个 API 使能一个任务等待一个事件的发生和返回控制而不是一直等待。在这个 API 中的函数可以用来为任务设置事件，立刻通知任务有事件被设置。osal_set_event( )功能描述：函数用来设置一个任务的事件标志原型：byte osal_set_event( byte task_id, UINT16 event_flag )参数：task_id ：任务标识event
6、_flag ：是个字节的位图，每个位特指一个事件。只有一个系统事件（SYS_EVENT_MSG），其他事件在接收任务中定义。返回值：ZSUCCESS 成功设置INVALID_TASK 无效任务3 时间管理 API这个允许内部任务（Z-Stack）以及应用层任务使用定时器。函数提供了启动和停止定时器的功能，定时器最小增量为 1MS。（1） osal_start_timer( )功能描述：启动一个定时器，当定时器终止时，指定的事件标志位被设置。通过在任务中调用 osal_start_timer 函数设置时间标志位。如果指明任务 ID，则可以用osal_start_timerEx()函数替代 osa
7、l_start_timer().原型:byte osal_start_timer(UINT16 event_id, UINT16 timeout_value);参数：event_id : 用户定义的事件标志位 event bit. 当定时器到点时，事件将通知任务。timeout_value ：定时值（ ms）返回值：ZSUCCESS Timer 成功开启NO_TIMER_AVAILABLE 无法开启（2） osal_start_timerEx( )功能描述：功能与 osal_start_timer()相近，只不过参数多了一个任务 ID，这个函数允许调用者为另一个任务启动定时器原型：byte o
8、sal_start_timerEx( byte taskID, UINT16 event_id, UINT16timeout_value);参数：参数 1：taskID 当定时器终止时，得到该事件的任务 ID参数 2：event_id,是用户定义的事件位，当定时器终止时，正在调用的任务将被通报参数 3：定时器事件被设置之前时间的计数返回值：ZSUCCESS Timer 成功开启NO_TIMER_AVAILABLE 无法开启（3）osal_stop_timer( )功能描述：停止正在运行的定时器，停止外部事件调用 osal_stop_timerEx()，可以停止不同任务的定时器。原型：byte
9、osal_stop_timer( UINT16 event_id );参数：event_id ：将要结束的目标事件（该事件是启动定时器的事件）定时器的标识符返回值：ZSUCCESS Timer 成功停止INVALID_EVENT_ID 无效事件（4）osal_stop_timerEx( )功能描述：结束外部事件的定时器，指明了任务的 ID原型：byte osal_stop_timerEx( byte task_id, UINT16 event_id );参数：参数 1：停止定时器所在的任务 ID参数 2：被停止定时器的标识符返回值ZSUCCESS Timer 成功停止INVALID_EVENT
10、_ID 无效事件（5）osal_GetSystemClock( )功能描述：读取系统时间原型：uint32 osal_GetSystemClock( void );参数：无返回值：系统时间（ms）4 中断管理 API这些 API 实现任务与外部中断的接口，函数允许一个任务关联每一个具体的中断程序程序，可以开关中断。在中断服务程序内，其他任务可以设置事件。（） osal_int_enable( )功能描述：函数用于使能中断。一旦允许中断发生将引起中断分配的服务程序运行。原型：byte osal_int_enable( byte interrupt_id )参数：interrupt_id ：被允许
11、的中断的标识符。返回值：ZSUCCESS Interrupt 成功使能INVALID_INTERRUPT_ID 无效中断（2）osal_int_disable( )功能描述：关闭中断原型：byte osal_int_disable( byte interrupt_id )参数：被禁止中断的标识符返回值：ZSUCCESS Interrupt 成功关闭INVALID_INTERRUPT_ID 无效中断5 任务管理 API该 API 用在添加和管理 OSAL 中的任务。每一个任务由任务初始化函数和时间处理函数组成。（1）osal_init_system()功能描述：该函数初始化 OSAL 系统。该函
12、数必须在启动任何一个 OSAL 函数之前被调用原型：byte osal_init_system( void )参数:无返回值：ZSUCCESS 成功（2）osal_start_system()功能描述：这个函数是系统任务的主循环函数，在循环里面将遍历所有的任务事件，为触发事件的任务调用任务事件处理函数。如果一个特定任务有事件发送，那么该函数就将调用该任务的事件处理函数。当事件处理完之后，将返回主循环。继续查找其他的任务事件。如果没有事件，函数将把处理器转到睡眠模式。原型：void osal_start_system( void )参数：无返回值：无（3）osal_self( )功能描述：这个函
13、数 返回正在被调用任务的任务标识符。如果在一个中断服务子程序中调用该函数将返回一个错误结果。 函数原型 byte osal_self( void ) 参数描述 无 返回值：返回值为当前活动的任务的任务标识符（4）osalTaskAdd( ) 功能描述：这个函数添加一个任务到任务系统中，一个任务由两个函数组成 初始化与信息处理。信息处理函数在事件时发生，而后处理其中之一，并返回其余到主循环中。 函数原型 /任务初始化函数原型 typedef void(*pTaskInitFn) (unsigned char task_id); /事件句柄函数原型 typedef unsigned short (
14、*pTaskEventHandlerFn)(unsigned char task_id,unsigned short event); /添加任务函数原型void osalTaskAdd(const pTaskInitFn pfnInit,const pTaskEventHandlerFn,pfnEventProcessor, const byte taskPriority); 参数描述 pfnInit 指向任务初始化函数的指针pfnEventProcessor 指向任务事件处理器函数的指针taskPriority 任务的优先级。值为 0 255 之间优先级 值 OSAL_TASK_PRIORI
15、TY_LOW 50 OSAL_TASK_PRIORITY_MED 130 OSAL_TASK_PRIORITY_HIGH 230 6 内存管理 API该 API 呈现一个简单的内存分配系统。这些函数允许动态内存分配。（1）osal_mem_alloc( ) 功能描述：这个函数是一个简单内存分配函数，如果成功则返回一个缓冲区的指针。 函数原型 oid *osal_mem_alloc(uint16 size); 参数描述 ize 缓冲区的大小 返回值 一个 void 指针指向新分配的缓冲区，如果没有足够的内存来分配，则返回一个 NULL 指针。（3） osal_mem_free 功能描述：这个函数
16、释放已分配的内存来重新使用。只有当内存已使用 osal_mem_alloc( )分配过才可以工作。 函数原型 oid osal_mem_free(void *ptr); 参数描述 ptr - 指向将被释放的缓冲区的指针，这个缓冲区之前必须被 osal_mem_alloc( )分配过使用。 返回值 无。 7. 电源管理 API 这里的函数描述了 OSAL 的电源管理系统，当 OSAL 安全的关闭接收器宇外部硬件并使处理器进入休眠模式时，该系统提供想应用/任务通报该事件的方法（1） osal_pwrmgr_task_state( ) 功能描述：该函数被每个任务调用，声明该任务是否需要节能，任务被创
17、建时，默认是节能模式。如果任务总是需要节能，那么就不需要调用该函数。函数原型 byte osal_pwrmgr_task_state(byte task_id,pwrmgr_state_t state); 参数描述 state 改变一任务电源状态。 类型 描述 PWRMGR_CONSERVE 打开节能模式，所有任务都须一致，为任务初始化的缺省模式。 PWRMGR_HOLD 关闭节能模式 返回值 返回值显示操作的结果。 返回值 描述 ZSUCCESS 成功 INVALID_TASK 无效任务(2) osal_pwrmgr_device()功能描述：该函数在上电或电源需求变更时调用（例如电源支持协
18、调器）。这一函数设置了大体的设备电源管理的开/关状态。该函数应当从中央控制实体（如 ZDO)被调用。原型：void osal_pwrmgr_state( byte pwrmgr_device );参数：pwrmgr_device ：更改或设置节电模式PWRMGR_ALWAYS_ON 无节电PWRMGR_BATTERY 开节电返回值：无8非易失性（NV）存储管理这部分讲述 OSAL NV 非易失性（NV）存储系统。系统提供了一种方式来为应用永久存放信息到设备内存中。他也可以用于某些堆栈条目的固定存储，这些 NV 函数被设计用来读取/ 写入用户定义的由任何数据类型组成的(如结构与数组)项目。用户可
19、以通过设定一适当的偏移量与长度读取或写入一个完整的项目或项目中的一个单元。 该 API为 NV 存储介质独有，与存储体本身没有关系。可以被 flash 或 eeprom 使用。 每个 NV 项目都有一个惟一的标识符，每个应用都有特定的 ID 值范围(其余 ID 值为保留，或为栈、平台所用)。如果你的应用创建了自己的 NV 项目，则必须从应用值范围内选一个 ID。如下0x0000 Reserved0x0001 0x0020 OSAL0x0021 0x0040 NWK0x0041 0x0060 APS0x0061 0x0080 Security0x0081 0x00A0 ZDO0x00A1 0x0
20、200 Reserved0x0201 0x0FFF Application0x1000 -0xFFFF Reserved在使用 API 时有一些重要的注意点：1)这些是模块化函数调用，一个操作需要花费几毫秒来完成，特别是 NV 写操作。另外，中断需求禁止几毫秒。最好是在与其他时间性操作上没有冲突的时刻来执行这些函数。例如，一个较佳的写 NV 项目时刻是接收器关闭的时候。 2) 不要经常性写 NV，它需要花费时间与能源，并且大多数的闪存都有一个最大擦除次数限制。 3) 如果一个或多个 NV 项目变更，特别是 Z-stack 的版本升级，它必须擦除且重新初始化 NV内存。否则，读与写已变更的 NV
21、 项目操作将失败或产生错误的结果。(1) osal_nv_item_init( ) 功能描述：初始化 NV 中的一条项目。这个函数检测 NV 项目的存在，如果不存在，则它用数据创建与初始化一个 NV 项目，如果有的话。 在调用 osal_nv_read( )或osal_nv_write( )前，每一个项目必须先调用该函数。 函数原型 yte osal_nv_item_init(uint16 id,uint16 len,void *buf); 参数描述 id 用户定义项目标识符 len 项目长度( 字节) buf 项目初始化数据指针，如果没有初始化数据，则设为 NULL. 返回值 返回值显示操作
22、的结果。 返回值 描述 ZSUCCESS 成功 NV_ITEM_UNINIT 成功但项目不存在(2) osal_nv_read( ) 功能描述：读取 NV 数据，这个函数被用来读取整个 NV 项目或一个项目中项目，读取的数据被复制到*buf 中。 函数原型 yte osal_nv_read( uint16 id, uint16 offset, uint16 len, void *buf); 参数描述 d 用户定义项目标识符 ffset 项目的内存偏移量 (字节) en 项目长度 (字节) buf 数据读取到该缓冲区 返回值 返回值显示操作的结果。 返回值 描述 ZSUCCESS 成功 NV_I
23、TEM_UNINIT 项目没有初始化 NV_OPER_FAILED 操作失败（2） nv_osal_write( ) 功能描述：写入数据到 NV 中，这个函数被用来写入整个 NV 项目或一个项目中的单元(通过一个偏移量来索引该项目)。 函数原型 byte osal_nv_write( uint16 id,uint16 offset,uint16 len,void *buf); 参数描述 id 用户定义项目标识符 offset 项目的内存偏移量 (字节) len 项目长度( 字节)*buf 要写入的数据 返回值 返回值显示操作的结果。 返回值 描述 ZSUCCESS 成功 NV_ITEM_UNINIT 项目没有初始化 NV_OPER_FAILED 操作失败 （3） osal_offsetof( ) 功能描述：该宏在一个结构中按字节计算一个单元的内存偏移量，它被 NV API 函数用来计算偏移量。函数原型 sal_offsetof(type,member) 参数描述 ype 结构类型 member 结构成员
