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

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

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

操作系统抽象层（OSAL）是被用来使Z-Stack协议栈的软件组件与特殊的出来环境无关。操作系统抽象层能独立于具体的出来环境，主要提供以下功能：

1、任务的注册，初始化和启动。

2、任务间的消息交换。

3、任务的同步。

4、中断处理。

5、定时器处理。

6、存储器的分配。

1 消息管理API

消息管理API为任务间或不同处理环境中的处理单元的消息交换提供一种手段。消息管理API中的函数使能一个任务分配或者释放消息缓冲区，发送命消息给另一个任务并接收响应消息。

1.1 osal_msg_allocate()

该函数被一个任务调用来分配一个消息缓冲区，该任务/函数将填写消息并通过调用osal_msg_send()函数来将消息发送给另一个任务。如果缓冲区不能被分配，msg_ptr将被置位NULL。（注意：本函数被用来分配一个缓冲区以便在两个任务之间发送信息（使用osal_msg_send()函数）。使用osal_mem_alloc()函数是分配存储器的一个块。）。

函数原型为：

uint8 * osal_msg_allocate( uint16 len )

其中参数：

len 为消息的长度。

函数返回值：一个指向为消息分配的缓冲区的指针。如果返回值为NULL表

示操作失败。

1.2 osal_msg_deallocate()

该函数被用来释放一个消息缓冲区。当一个任务（或处理单元）在它已经完成对接收到的消息处理后调用本函数。

函数原型为：

uint8 osal_msg_deallocate( uint8 *msg_ptr )

其中参数：

msg_ptr 为指向需要被释放的消息缓冲区的指针。

函数返回值：

1.3 osal_msg_send()

该函数被一个任务发送一个命令或数据信息到其他任务或处理元素中。destination_task标识符字段必须指向一个有效的系统任务。当调用osal_create_task()函数来开始一个任务的时候任务标识符被分配给该任务。本函数将同时触发目标任务事件列表中的SYS_EVENT_MSG事件。

函数原型为：

uint8 osal_msg_send( uint8 destination_task, uint8 *msg_ptr ) 其中参数：

destination_task 为接收消息的任务ID。

msg_ptr 为指向包含消息的缓冲区的指针。该参数必须是通过osal_msg_allocate()函数分配的一个有效的缓冲区的指针。

函数返回值：

1.4 osal_msg_receive()

该函数被一个任务调用来取回一条已经收到的命令信息。调用该函数的任务必须在处理完消息后使用osal_msg_deallocate()函数来释放消息缓冲区。

函数原型为：

uint8 *osal_msg_receive( uint8 task_id )

其中参数：

task_id 为调用该函数的任务（消息被发往给它）的标识符。

函数返回值：一个指向一个包含消息的缓冲区的指针。如果没有接收到消息返回值为NULL。

2 任务同步API

任务同步API可以使能一个任务去等待事件的发生并返回控制。任务同步API中的函数可以被用来为一个任务设置事件，并且任何事件被触发时通知该任务。

2.1 osal_set_event()

该函数被调用来为一个任务设置事件标志。

函数原型：

uint8 osal_set_event( uint8 task_id, uint16 event_flag )

其中参数：

task_id 将要被设置事件标志的任务ID。

event_flag为一个2字节的位图，每位定义一个事件。仅有一个系统事件

（SYS_EVENT_MSG）其余事件/位被接收任务定义。

函数返回值：

3 定时器管理API

定时器管理API使能内部（Z-Stack）任务像外部（应用级）任务一样对定时器的使用。定时器管理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一个用户定义的事件位。定时器到期时，调用任务将被通知（事件）。 timeout_value定时器事件被触发以前的总时间（以毫秒为单位）。

函数返回值：

3.2 osal_stop_timerEx()

该函数被调用来停止一个已经启动的定时器。如果成功，该函数为调用任务取消定时器并阻止与该定时器相关的事件被触发。使用osal_stop_timerEx函数意味着定时器正运行在调用osal_stop_timerEx函数的任务的上下文环境中。

函数原型：

uint8 osal_stop_timerEx( uint8 task_id, uint16 event_id ) 其中参数：

task_id一个任务ID，停止定时器就是为了这个任务而操作的。

event_id 将要被停止的定时器的标识符（事件）。

函数返回值：

3.3 osal_GetSystemClock()

该函数被调用来读取系统时钟。

函数原型：

uint32 osal_GetSystemClock( void )

其中参数：无

函数返回值：以毫秒为单位的系统时钟。

4 中断管理API

中断管理API可以使能一个任务去与外部中断进行接口。中断管理API中的函数允许一个任务去与每一个中断关联一个专门的服务例程。中断可以被使能或禁止。在中断服务例程中。事件可被其他任务触发。

4.1 osal_int_enable()

本函数被调用来使能一个中断，中断一旦使能，发生中断时，与该中断相关的服务例程将被调用。

函数原型：

uint8 osal_int_enable( uint8 interrupt_id )

其中参数：

interrupt_id 将被使能的中断的标识符。

函数返回值：

4.2 osal_int_disable()

本函数被调用来禁止一个中断。当一个被禁止的中断发生时，与该中断相关的服务例程将不被调用。

函数原型：

uint8 osal_int_disable( uint8 interrupt_id )

其中参数：

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()

该函数是任务系统中的主循环函数。它查看所有的任务事件并为具有事件的任务调用事件处理函数。如果特殊任务有事件，该函数将为这个任务调用事件处理例程来处理这些事件。相应的任务的事件处理例程每次处理一个事件。在一个事件被处理后，其余的事件将被返回到主循环中等待下一次处理。如果没有事件（多所有任务而言），被函数将使处理器进入睡眠模式。

函数原型：

void osal_start_system( void )

其中参数：无

函数返回值：无

6 存储器管理API

存储器管理API是一个简单的存储器分配系统。存储器管理API中的函数允许动态存储器分配。

6.1 osal_mem_alloc()

本函数是一个简单的存储器分配函数，它返回一个指向一个缓冲区的指针（如果成功）。

函数原型：

void *osal_mem_alloc( uint16 size )

其中参数：

size 希望获得的缓冲区的字节数量。

函数返回值：一个无效指针（应该被分配给一个预期的缓冲区类型）指向新分配的缓冲区。若返回NULL指针，表示没有足够的存储器来分配。

6.2 osal_mem_free()

本函数释放已被分配的存储器以便再次使用。本函数只能在存储器已经被使用osal_mem_alloc()函数分配过的情况下工作。

函数原型：

void osal_mem_free( void *ptr )

其中参数：

ptr指向准备被释放的缓冲区的指针。该缓冲区先前必须已经被分配（使用osal_mem_alloc()函数）。

函数返回值：无

7 电源管理API

操作系统抽象层（OSAL）的电源管理系统为应用/任务提供了一种方式：当安全的关闭了接收器和外部硬件并且使处理器处于睡眠状态时去通知操作系统抽象层（OSAL）。

有两个函数来控制电源管理。第一个，osal_pwrmgr_device()函数被调用来设置设备的级别模式（节点模式或非节点模式）。然后是任务电源状态，每一个任务可以通过调用osal_pwrmgr_task_state(PWRMGR_HOLD)来阻止电源管理使用节电模式。如果一个任务“控制”了电源管理，那么它将需要通过调用osal_pwrmgr_task_state(PWRMGR_CONSERVE)来允许电源管理在节电模式下继续工作。

默认情况下，当任务被初始化时，每一个任务的电源状态被设置为

PWRMGR_CONSERVE，因此如果一个任务不想阻止节电模式（状态不改变）那就不

需要调用osal_pwrmgr_task_state()函数。

电源管理在进入节电模式之前将查看设备模式和所有任务的电源状态集合。

7.1 osal_pwrmgr_device()

本函数在上电时或者要求更换电源（例如，协调器背面的电池）时被调用。 本函数设置设备的电源管理的全部开/关状态。本函数应当被一个中央控制实体（如 ZDO）调用。

函数原型：

void osal_pwrmgr_device( uint8 pwrmgr_device )

其中参数：

pwrmgr_device 改变或者设置电源节电模式，类型为：

函数返回值：无 7.2 osal_pwrmgr_task_state()

本函数被每一个任务调用进入一个状态不管该任务是否想节电。任务将调用本函数来决定是否它想让操作系统抽象层（OSAL）节电或者不节电。默认情况下，当一个任务被创建后，它自己的电源状态被设置为节电，如果这个任务希望一直保持节电，它不需要调用本函数。

函数原型：

uint8 osal_pwrmgr_task_state( uint8 task_id, uint8 state )

其中参数：

task_id任务ID

state改变一个任务的电源状态，state类型：

函数返回值：

8 非易失性存储器API

操作系统抽象层（OSAL）的非易失性（NV）存储器系统为应用提供了一个将信息持久的保存在设备的存储器中的方式。它也被协议栈用来持久的存储zigbee规范要求的必要项目。NV函数被设计用来读和写用户自定义的项目（由任意数据类型，例如结构体或数据组成）。通过设置恰当的偏移地址和长度，用户可以读或写一个完整的项目或者项目的一个单元。非易失性存储器API与NV存储介质无关，可以在flash或EEPROM上实施。

每一个NV项目有一个唯一的ID。应用由一个特定的ID值范围，其中的某些ID值被保留或被协议栈或被开发平台所用。如果应用需要创建自己的NV项目，必须从应用值范围内选择一个ID，见下表：

在使用非易失性存储器API时需要认真考虑以下几点：

1、它们都是阻塞函数，一个操作可能需要数毫秒才能完成，与其是针对NV的写操作。另外，中断可能被禁止数毫秒。最好是在当它不与其他时间关键性操作冲突时执行这些函数。例如，写NV项目的一个好时机是当接收器关闭的时候。

2、不要频繁的进行NV写操作。它耗时耗电，并且大多数flash设备都有一个循环擦除的次数限制。

3、如果一个或多个NV项目的结构发生改变，特别是当从Z-Stack的一个版本升级到另一个版本，擦除和重新初始化NV存储器时必要的。否则，在已改变的NV项目上进行读和写操作将会失败或产生错误的结果。

8.1 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。

函数返回值：

8.2 osal_nv_read()

该函数从NV读取数据。本函数可以被用来从NV读取一个实体项目或读取通

过偏移索引到项目中的一个单元。读取的数据拷贝到*buf。

函数原型：

uint8 osal_nv_read( uint16 id, uint16 ndx, uint16 len, void *buf ) 其中参数：

id 用户自定义项目ID。

ndx 项目在存储器中的偏移（以字节为单位）。

len 项目长度（以字节为单位）。

buf 数据将被读取到该缓冲区。

函数返回值：

8.3 osal_nv_write()

该函数为写数据到NV，本函数可以被用来写一个实体项目到NV或者写一个通过偏移索引到项目中的一个单元到NV。

函数原型：

uint8 osal_nv_write( uint16 id, uint16 ndx, uint16 len, void *buf ) 其中参数：

id 用户自定义项目ID。

ndx 项目在存储器中的偏移（以字节为单位）。

len 项目长度（以字节为单位）。

buf 数据将被写入到该缓冲区。

函数返回值：

9 协议栈操作系统抽象层（OSAL）其他API

内存复制函数：

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 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 )

设置系统时钟：

void osal_setClock( UTCTime newTime )

获取当前系统时钟：

UTCTime osal_getClock( void )

内存初始化：

void osal_mem_init( void )

非易失性存储初始化：

static uint8 initNV( void )

非易失性存储分页设置：

static void setPageUse( uint8 pg, uint8 inUse )

非易失性存储初始化页：

static uint16 initPage( uint8 pg, uint16 id, uint8 findDups ) 非易失性存储页擦除：

static void erasePage( uint8 pg )

查找一个非易失性存储变量所在的页：

static uint16 findItem( uint16 id )

电源管理初始化：

void osal_pwrmgr_init( void )

系统时钟初始化：

void osalTimerInit( void )

定时事件添加函数：

osalTimerRec_t * osalAddTimer( uint8 task_id, uint16 event_flag, uint16

timeout )

查找定时事件：

osalTimerRec_t *osalFindTimer( uint8 task_id, uint16 event_flag ) 删除定时事件：

void osalDeleteTimer( osalTimerRec_t *rmTimer )

获取一个定时事件的溢出时间：

uint16 osal_get_timeoutEx( uint8 task_id, uint16 event_id )

获取当前活动的定时事件：

uint8 osal_timer_num_active( void ) 获取当前系统时间：

uint32 osal_GetSystemClock( void )