Z-Stack协议栈操作系统抽象层API

1、Z-Stack协议栈操作系统抽象层(OSAL) API操作系统抽象层(OSAL)是被用来使Z-Stack协议栈的软件组件与特殊的出 来环境无关。操作系统抽象层能独立于具体的出来环境，主要提供以下功能：1、任务的注册，初始化和启动。2、任务间的消息交换。3、任务的同步。4、中断处理。5、定时器处理。6、存储器的分配。1消息管理API消息管理API为任务间或不同处理环境中的处理单元的消息交换提供一种 手段。消息管理API中的函数使能一个任务分配或者释放消息缓冲区，发送命消 息给另一个任务并接收响应消息。osal_msg_allocate()该函数被一个任务调用来分配一个消息缓冲区，该任务/函数将填

2、写消息并 通过调用osal_msg_send()函数来将消息发送给另一个任务。如果缓冲区不能被 分配，msg_ptr将被置位NULL。(注意：本函数被用来分配一个缓冲区以便在两 个任务之间发送信息(使用osal_msg_send()函数)。使用osal_mem_alloc()函 数是分配存储器的一个块。)。函数原型为：uint8 * osal_msg_allocate( uint16 len )其中参数：len为消息的长度。函数返回值：一个指向为消息分配的缓冲区的指针。如果返回值为NULL表示操作失败。osal_msg_deallocate()该函数被用来释放一个消息缓冲区。当一个任务(或处理

3、单元)在它已经完 成对接收到的消息处理后调用本函数。函数原型为：uint8 osal_msg_deallocate( uint8 *msg_ptr )其中参数：msg_ptr为指向需要被释放的消息缓冲区的指针。函数返回值：返回值描述SUCCESS释放成功INVALID_MSG_POINTER无效的消息指针MSG_BUFFER_NOT_AVAIL缓冲区在排队等候osal_msg_send()该函数被一个任务发送一个命令或数据信息到其他任务或处理元素中。destination_task标识符字段必须指向一个有效的系统任务。当调用 osal_create_task()函数来开始一个任务的时候任务标识

4、符被分配给该任务。本 函数将同时触发目标任务事件列表中的SYS_EVENT_MSG事件。函数原型为：uint8 osal_msg_send( uint8 destination_task, uint8 *msg_ptr )其中参数：destination_task为接收消息的任务ID。msg_ptr为指向包含消息的缓冲区的指针。该参数必须是通过 osal_msg_allocate()函数分配的一个有效的缓冲区的指针。函数返回值：返回值描述SUCCESS消息发送成功INVALID_MSG_POINTER无效的消息指针INVALID_TASKdestination_task 无效osal_msg_

5、receive()该函数被一个任务调用来取回一条已经收到的命令信息。调用该函数的任务 必须在处理完消息后使用osal_msg_deallocate()函数来释放消息缓冲区。函数原型为：uint8 *osal_msg_receive( uint8 task_id )其中参数：task_id为调用该函数的任务(消息被发往给它)的标识符。函数返回值：一个指向一个包含消息的缓冲区的指针。如果没有接收到消息 返回值为NULL。2任务同步API任务同步API可以使能一个任务去等待事件的发生并返回控制。任务同步 API中的函数可以被用来为一个任务设置事件，并且任何事件被触发时通知该任 务。osal_set_

6、event()该函数被调用来为一个任务设置事件标志。函数原型：uint8 osal_set_event( uint8 task_id, uint16 event_flag )其中参数：task_id将要被设置事件标志的任务ID。event_flag为一个2字节的位图，每位定义一个事件。仅有一个系统事件（SYS_EVENT_MSG ）其余事件/位被接收任务定义。函数返回值:返回值描述SUCCESS设置成功INVALID_MSG_POINTER源任务无效3定时器管理API定时器管理API使能内部（Z-Stack）任务像外部（应用级）任务一样对定 时器的使用。定时器管理API中提供了一些函数去启动和

7、停止一个定时器。定时 器可以被设置成1毫秒的增量。3.1 osal_start_timerEx（）该函数被调用来启动一个定时器。当定时器到期时，该特定事件对应的位被 置位。事件将被在调用osal_start_timerEx函数的任务中被触发。函数原型：uint8 osal_start_timerEx（ uint8 taskID, uint16 event_id, uint16 timeout_value ）其中参数：taskID当定时器到期时获得事件的这个任务的ID。event_id 一个用户定义的事件位。定时器到期时，调用任务将被通知（事件）。timeout_value定时器事件被触发以前的

8、总时间（以毫秒为单位）。函数返回值：返回值描述SUCCESS定时器启动成功NO_TIMER_AVAIL无法启动定时器osal_stop_timerEx()该函数被调用来停止一个已经启动的定时器。如果成功，该函数为调用任务 取消定时器并阻止与该定时器相关的事件被触发。使用osal_stop_timerEx函数 意味着定时器正运行在调用osal_stop_timerEx函数的任务的上下文环境中。函数原型：uint8 osal_stop_timerEx( uint8 task_id, uint16 event_id )其中参数：task_id 一个任务ID，停止定时器就是为了这个任务而操作的。eve

9、nt_id将要被停止的定时器的标识符(事件)。函数返回值：返回值描述SUCCESS定时器停止成功INVALID_EVENT_ID无效事件osal_GetSystemClock()该函数被调用来读取系统时钟。函数原型：uint32 osal_GetSystemClock( void )其中参数：无函数返回值：以毫秒为单位的系统时钟。4中断管理API中断管理API可以使能一个任务去与外部中断进行接口。中断管理API中的 函数允许一个任务去与每一个中断关联一个专门的服务例程。中断可以被使能或 禁止。在中断服务例程中。事件可被其他任务触发。osal_int_enable()本函数被调用来使能一个中断，

10、中断一旦使能，发生中断时，与该中断相关 的服务例程将被调用。函数原型：uint8 osal_int_enable( uint8 interrupt_id )其中参数：interrupt_id将被使能的中断的标识符。函数返回值：返回值描述SUCCESS中断使能成功INVALID_INTERRUPT_ID无效中断osal_int_disable()本函数被调用来禁止一个中断。当一个被禁止的中断发生时，与该中断相关 的服务例程将不被调用。函数原型：uint8 osal_int_disable( uint8 interrupt_id )其中参数：interrupt_id将被禁止的中断标识符。函数返回值

11、：返回值描述SUCCESS中断禁止成功INVALID_INTERRUPT_ID无效中断5任务管理API任务管理API被用来在操作系统抽象层(OSAL)系统中添加和管理任务。osal_init_system()本函数初始化操作系统抽象层(OSAL)系统。在启动过程中，该函数必须在 使用其他任何OSAL函数OSAL函数之前被调用。函数原型：uint8 osal_init_system( void )其中参数：无函数返回值：SUCCESS成功osal_start_system()该函数是任务系统中的主循环函数。它查看所有的任务事件并为具有事件的 任务调用事件处理函数。如果特殊任务有事件，该函数将为这

12、个任务调用事件处 理例程来处理这些事件。相应的任务的事件处理例程每次处理一个事件。在一个 事件被处理后，其余的事件将被返回到主循环中等待下一次处理。如果没有事件 (多所有任务而言)，被函数将使处理器进入睡眠模式。函数原型：void osal_start_system( void )其中参数：无函数返回值：无6存储器管理API存储器管理API是一个简单的存储器分配系统。存储器管理API中的函数允 许动态存储器分配。osal_mem_alloc()本函数是一个简单的存储器分配函数，它返回一个指向一个缓冲区的指针 (如果成功)。函数原型：void *osal_mem_alloc( uint16 si

13、ze )其中参数：size希望获得的缓冲区的字节数量。函数返回值：一个无效指针(应该被分配给一个预期的缓冲区类型)指向新 分配的缓冲区。若返回NULL指针，表示没有足够的存储器来分配。6.2 osal_mem_free()本函数释放已被分配的存储器以便再次使用。本函数只能在存储器已经被使 用osal_mem_alloc()函数分配过的情况下工作。函数原型：void osal_mem_free( void *ptr )其中参数：ptr指向准备被释放的缓冲区的指针。该缓冲区先前必须已经被分配(使用 osal_mem_alloc()函数)。函数返回值：无7电源管理API操作系统抽象层(OSAL)的电

14、源管理系统为应用/任务提供了一种方式：当 安全的关闭了接收器和外部硬件并且使处理器处于睡眠状态时去通知操作系统 抽象层(OSAL)。有两个函数来控制电源管理。第一个，osal_pwrmgr_device()函数被调用来 设置设备的级别模式(节点模式或非节点模式)。然后是任务电源状态，每一个 任务可以通过调用osal_pwrmgr_task_state(PWRMGR_HOLD)来阻止电源管理使 用节电模式。如果一个任务“控制”了电源管理，那么它将需要通过调用 osal_pwrmgr_task_state(PWRMGR_CONSERVE)来允许电源管理在节电模式下继续 工作。默认情况下，当任务被初

15、始化时，每一个任务的电源状态被设置为 PWRMGR_CONSERVE，因此如果一个任务不想阻止节电模式(状态不改变)那就不 需要调用 osal_pwrmgr_task_state()函数。电源管理在进入节电模式之前将查看设备模式和所有任务的电源状态集合。osal_pwrmgr_device()本函数在上电时或者要求更换电源(例如，协调器背面的电池)时被调用。本函数设置设备的电源管理的全部开/关状态。本函数应当被一个中央控制 实体(如ZDO)调用。函数原型：void osal_pwrmgr_device( uint8 pwrmgr_device )其中参数：pwrmgr_device改变或者设置

16、电源节电模式，类型为：类型描述PWRMGR_ALWAYS_ON选择该类型将没有节电模式，设备有电源供电PWRMGR_BATTERY打开节电模式函数返回值：无osal_pwrmgr_task_state()本函数被每一个任务调用进入一个状态不管该任务是否想节电。任务将调用 本函数来决定是否它想让操作系统抽象层(OSAL)节电或者不节电。默认情况下， 当一个任务被创建后，它自己的电源状态被设置为节电，如果这个任务希望一直 保持节电，它不需要调用本函数。函数原型：uint8 osal_pwrmgr_task_state( uint8 task_id, uint8 state )其中参数：task_i

17、d 任务 IDstate改变一个任务的电源状态，state类型：类型描述PWRMGR_CONSERVE开节电模式，所有任务必须同意。这是一个任 务初始化时的默认状态PWRMGR_HOLD关闭节电模式函数返回值:类型描述SUCCESS成功INVALID_TASK无效任务8非易失性存储器API操作系统抽象层（OSAL）的非易失性（NV）存储器系统为应用提供了一个将 信息持久的保存在设备的存储器中的方式。它也被协议栈用来持久的存储 zigbee规范要求的必要项目。NV函数被设计用来读和写用户自定义的项目（由 任意数据类型，例如结构体或数据组成）。通过设置恰当的偏移地址和长度，用 户可以读或写一个完整

18、的项目或者项目的一个单元。非易失性存储器API与NV 存储介质无关，可以在flash或EEPROM上实施。每一个NV项目有一个唯一的ID。应用由一个特定的ID值范围，其中的某些 ID值被保留或被协议栈或被开发平台所用。如果应用需要创建自己的NV项目， 必须从应用值范围内选择一个ID，见下表：值用户0 x0000保留0 x0001- 0 x0020操作系统抽象层0 x0021- 0 x0040网络层0 x0041- 0 x0060应用支持子层0 x0061- 0 x0080安全0 x0081- 0 x00A0ZigBee设备对象0 x00A1- 0 x0200保留0 x0201- 0 x0FFF

19、应用0 x1000- 0 xFFFF保留在使用非易失性存储器API时需要认真考虑以下几点：1、它们都是阻塞函数，一个操作可能需要数毫秒才能完成，与其是针对NV 的写操作。另外，中断可能被禁止数毫秒。最好是在当它不与其他时间关键性操 作冲突时执行这些函数。例如，写NV项目的一个好时机是当接收器关闭的时候。2、不要频繁的进行NV写操作。它耗时耗电，并且大多数flash设备都有一 个循环擦除的次数限制。3、如果一个或多个NV项目的结构发生改变，特别是当从Z-Stack的一个版 本升级到另一个版本，擦除和重新初始化NV存储器时必要的。否则，在已改变 的NV项目上进行读和写操作将会失败或产生错误的结果。

20、osal_nv_item_init()本函数在NV中初始化一个项目。该函数检查NV中的一个项目是否存在。如 果它不存在，它将被创建和用函数参数传递的数据初始化。在调用 osal_nv_read()或osal_nv_write()函数之前，本函数必须被每一个项目调用。函数原型：uint8 osal_nv_item_init( uint16 id, uint16 len, void *buf )其中参数：id用户自定义ID。len项目长度(以字节为单位)。buf指向项目初始化数据的指针。若没有初始化数据，被置为NULL。函数返回值：返回值描述ZSUCCESS成功NV_ITEM_UNINIT成功但项

21、目不存在NV_OPER_FAILED操作失败osal_nv_read()该函数从NV读取数据。本函数可以被用来从NV读取一个实体项目或读取通过偏移索引到项目中的一个单元。读取的数据拷贝到*buf。函数原型：uint8 osal_nv_read（ uint16 id, uint16 ndx, uint16 len, void *buf ）其中参数：id用户自定义项目ID。ndx项目在存储器中的偏移（以字节为单位）。len项目长度（以字节为单位）。buf数据将被读取到该缓冲区。函数返回值：返回值描述ZSUCCESS成功NV_ITEM_UNINIT项目未被初始化NV_OPER_FAILED操作失败8

22、.3 osal_nv_write（）该函数为写数据到NV，本函数可以被用来写一个实体项目到NV或者写一个 通过偏移索引到项目中的一个单元到NV。函数原型：uint8 osal_nv_write（ uint16 id, uint16 ndx, uint16 len, void *buf ）其中参数：id用户自定义项目ID。ndx项目在存储器中的偏移（以字节为单位）。len项目长度（以字节为单位）。buf数据将被写入到该缓冲区。函数返回值：返回值描述ZSUCCESS成功NV_ITEM_UNINIT项目未被初始化NV_OPER_FAILED操作失败9协议栈操作系统抽象层（OSAL ）其他API内存复

23、制函数：void *osal_memcpy( void *dst, const void GENERIC *src, unsigned int len ) 内存倒置函数：void *osal_revmemcpy( void *dst, const void GENERIC *src, unsigned int len )内存比较函数：uint8 osal_memcmp( const void GENERIC *src1, const void GENERIC *src2, unsigned int len )内存分配函数：void *osal_memset( void *dest, uint8

24、 value, int len )随机数生成函数：uint16 osal_rand( void )系统事件发现函数：osal_event_hdr_t *osal_msg_find(uint8 task_id, uint8 event)系统消息入列：void osal_msg_enqueue( osal_msg_q_t *q_ptr, void *msg_ptr )系统消息出列：void *osal_msg_dequeue( osal_msg_q_t *q_ptr )删除事件函数：uint8 osal_clear_event( uint8 task_id, uint16 event_flag )中断注册函数：uint8 osal_isr_register( uint8 interrupt_id, void (*isr_ptr)( uint8* )更新系统时间：void osalTimeUpdate( void )系统时钟更新：static void osalClockUpdate( uint16 elapsedMSec )设置系统时钟