ZStack协议栈操作系统抽象层OSALAPI.docx

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

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

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

4、osal_create_task()函数来开始一个任务的时候任务标识符被分配给该任务。本函数将同时触发目标任务事件列表中的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无效的消息指针INVALI

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

6、为一个任务设置事件，并且任何事件被触发时通知该任务。2.1 osal_set_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）任务像

7、外部（应用级）任务一样对定时器的使用。定时器管理API中提供了一些函数去启动和停止一个定时器。定时器可以被设置成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一个用户定义的事件位。定时器到期时，调

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

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

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

11、 interrupt_id )其中参数：interrupt_id将被禁止的中断标识符。函数返回值：返回值描述SUCCESS中断禁止成功INVALID_INTERRUPT_ID无效中断5 任务管理API任务管理API被用来在操作系统抽象层（OSAL）系统中添加和管理任务。5.1 osal_init_system()本函数初始化操作系统抽象层（OSAL）系统。在启动过程中，该函数必须在使用其他任何OSAL函数OSAL函数之前被调用。函数原型：uint8 osal_init_system( void )其中参数： 无函数返回值：SUCCESS成功5.2 osal_start_system()该函数是

12、任务系统中的主循环函数。它查看所有的任务事件并为具有事件的任务调用事件处理函数。如果特殊任务有事件，该函数将为这个任务调用事件处理例程来处理这些事件。相应的任务的事件处理例程每次处理一个事件。在一个事件被处理后，其余的事件将被返回到主循环中等待下一次处理。如果没有事件（多所有任务而言），被函数将使处理器进入睡眠模式。函数原型：void osal_start_system( void )其中参数：无函数返回值：无6 存储器管理API存储器管理API是一个简单的存储器分配系统。存储器管理API中的函数允许动态存储器分配。6.1 osal_mem_alloc()本函数是一个简单的存储器分配函数，它返

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

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

15、te(PWRMGR_CONSERVE)来允许电源管理在节电模式下继续工作。默认情况下，当任务被初始化时，每一个任务的电源状态被设置为PWRMGR_CONSERVE，因此如果一个任务不想阻止节电模式（状态不改变）那就不需要调用osal_pwrmgr_task_state()函数。电源管理在进入节电模式之前将查看设备模式和所有任务的电源状态集合。7.1 osal_pwrmgr_device()本函数在上电时或者要求更换电源（例如，协调器背面的电池）时被调用。本函数设置设备的电源管理的全部开/关状态。本函数应当被一个中央控制实体（如 ZDO）调用。函数原型：void osal_pwrmgr_device( uint8 pwrmgr_device )其中参数：pwrmgr_device 改变或者设置电源节电模式，类型为：类型描述PWRMGR_ALWAYS_ON选择该类型将没有节电模式，设备有电源供电PWR