OSALAPI介绍

OSAL 层是与协议栈互为独立的,但是整个协议都要基于OS 才能运行。OSAL 提供如
下服务和管理:
⚬ 信息管理;
⚬ 任务同步;
⚬ 时间管理;
⚬ 中断管理;
⚬ 任务管理;
⚬ 内存管理;
⚬ 电源管理;
⚬ 非易失存储管理。

1.信息管理API

该API为任务间的信息交换或者外部处理事件(例如:中断服务程序或一个控制循环内的函数调用等)提供一种管理机制。它包括允许任务分配和不分配信息缓存,发送命令信息到其他任务和接收应答信息等API函数。

1) osal_msg_allocate( )

函数原型:byte*osal_msg_allocate(uint16len)

功能描述:为信息分配缓存空间。当任务调用或函数被调用时,该空间被信息填充或调用发送信息函数osal_msg_send()发送缓存空间的信息到其他任务。如果该空间不能被分配,那么msg_ptr将设置为空(NULL)。

输入参数:len———信息的长度。

输 出:指向该信息分配的信息存储空间。如果一个空(NULL)指针返回,那么该信息缓存空间分配失败。

注意:该函数不能与函数osal_mem_alloc()混淆,osal_mem_alloc()函数是用于为在任务间发送信息(osal_msg_send())分配缓冲区的。用该函数也可以分配一个存储空间。

2) osal_msg_deallocate( )

功能描述:信息处理分配缓存。该函数通过一个任务(或一个处理过程)调用后完成处理一个接收的信息。

函数原型:byteosal_msg_deallocate(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 事件。

函数原型:byteosal_msg_send(bytedestination_task,byte*msg_ptr)

输入参数:destination_task———接收信息的任务ID。

msg_ptr———指向包含该信息的指针,必须为osal_msg_allocate()函数分配的有效数据缓存。

输 出:返回1字节指示操作的结果,参数如下:

ZSUCCESS :信息发送成功。

INVALID_MSG_POINTER :无效的信息指针。

INVALID_TASK :无效的目的任务ID。

4) osal_msg_receive( )

功能描述:一个任务接收一个命令信息调用该函数。该任务在处理完该信息之后,必须调用osal_msg_deallocate()函数为该信息分配信息缓存。

函数原型:byte*osal_msg_receive(bytetask_id )

输入参数:task_id———运行任务的标志符(信息归属的任务)。

输 出:返回一个包含该信息存储区的指针。如果没有接收信息,则为空(NULL)。

2.同步任务API

该API允许一个任务等待某个事件的发生并返回等待期间的控制。该API的功能是为某个任务设置事件,一旦任何一个事件被设置就修改该任务。osal_set_event( )

功能描述:该函数为某个任务设置事件标志。

原型:byteosal_set_event(bytetask_id,UINT16event_flag )

输入参数:task_id———任务标志符。为该任务设置事件的任务标志符。vent_flag———是2字节的位图,每1 位都对应一个事件。当仅有一个系统事件(SYS_EVENT_MSG)时,只有符合的事件/位被接收任务定义。

输 出:返回该操作的结构。

ZSUCCESS :成功。

INVALID_TASK :无效任务。

3.时间管理API

该API允许定时器被内部(Z Stack)任务和外部(应用水平)任务使用。该API系统开始和停止一个定时器的功能,这些定时器能用毫秒设置。

1) osal_start_timer( )

功能描述:启动一个定时器。当定时器终止时,指定的事件标志位被设置。通过在任务中调用osal_start_timer函数设置事件标志位。如果指明任务ID,则可以用osal_start_timerEx()函数替代函数osal_start_timer()。

函数原型:byteosal_start_timer(UINT16event_id,UINT16timeout_value)

输入参数:event_id———用户定义的事件标志位。当定时器终止时,该运行的任务将被通报(事件)。timeout_value———定时器事件被设置之前时间的计数(ms)。

返回:指示操作的结果,参数如下:

ZSUCCESS :定时器启动成功。

NO_TIMER_AVAILABLE :不能启动定时器。

2) osal_start_timerEx( )

功能描述:该函数与osal_start_timer()函数类似,只不过参数多了一个任务ID。允许调用者设置另一个任务的定时器。

函数原型:byteosal_start_timerEx(bytetaskID,UINT16event_id,UINT16timeout_value)

输入参数:taskID———当定时器终止时,得到该事件的任务ID。

event_idis———用户定义的事件位。当定时器终止时,正调用的任务将被通报(事件)。

timeout_value———定时器事件被设置之前时间的计数(ms)。

返回:指示操作结果,参数如下:

ZSUCCESS :定时器启动成功。

NO_TIMER_AVAILABLE :不能启动定时器。

3) osal_stop_timer( )

功能描述:停止已经被启动的定时器。如果成功,则该函数将取消定时器并且防止该定时器分配的任务事件的设置。该函数可以停止正在运行任务的定时器,与osal_stop_timerEx()可以停止不同任务的定时器有区别。

函数原型:byteosal_stop_timer(UINT16event_id )

输入参数:event_id———被停止定时器的标志符。

返回:指示操作结果,参数如下:

ZSUCCESS:定时器停止成功。

INVALID_EVENT_ID :无效事件。

4) osal_stop_timerEx( )

功能描述:该函数功能类似osal_stop_timer,只是它指明了任务ID。

函数原型:byteosal_stop_timerEx(bytetask_id,UINT16event_id )

输入参数:task_id———停止定时器所在的任务ID。

event_idi———被停止定时器的标志符。

返回:指示操作结果,参数如下:

ZSUCCESS:定时器停止成功。

INVALID_EVENT_ID :无效事件。

5) osal_GetSystemClock( )

功能描述:读系统时钟。

函数原型:uint32osal_GetSystemClock(void )

输入参数:无。

返回:系统时钟(ms)。

4.中断管理API

这些API是外部中断和任务的接口。这些API函数允许一个任务为每个中断分配指定的服务程序。这些中断能被允许或禁止。在服务程序内,可能为其他的任务设置事件。

1) osal_int_enable( )

功能描述:允许中断。一旦允许,中断发生将引起为该中断分配的服务程序运行。

函数原型:byteosal_int_enable(byteinterrupt_id )

输入参数:interrupt_id———被允许中断的标志符。

返回:指示操作的结果,参数如下:

ZSUCCESS :中断允许成功。

INVALID_INTERRUPT_ID :无效的中断。

2) osal_int_disable( )

功能描述:禁止某个中断。当中断禁止后,为该中断分配的服务程序就不能再运行。

函数原型:byteosal_int_disable(byteinterrupt_id )

输入参数:interrupt_id———被禁止中断的标识符。

返回:操作的结果,参数如下:

ZSUCCESS:中断禁止成功。

INVALID_INTERRUPT_ID :无效中断。

5.任务管理API

该API用于添加和管理OSAL 中的任务。

1) osal_init_system()

功能描述:初始化OSAL 系统。该函数必须被调用在启动任何一个OSAL 函数之前。函数原型:byteosal_init_system(void )

输入参数:无。

返回:操作结果的值,参数如下:

ZSUCCESS :成功Success。

2) osal_start_system()

功能描述:该函数是任务系统的主循环函数。它将查询所有的任务事件并对每个任务事件调用任务事件处理函数。如果某个特定的任务有事件发生,那么该函数就将调用该任务事件的处理函数。如果某事件发生并做了时间处理,则该处理函数完后将返回该主循环函数,继续查找其他任务事件。如果所有的任务没有事件发生,那么该函数将使处理器进入睡眠模式。

函数原型:voidosal_start_system(void )

输入参数:无。

返回:无。

3) osal_self()

功能描述:该函数返回当前运行任务的ID 号。如果在一个中断服务程序里调用该函数,将返回一个错误的结果。

函数原型:byteosal_self(void )

输入参数:无。

返回:返回当前激活运行的任务ID。

4) osalTaskAdd()

功能描述:该函数在OSAL 系统里添加一个任务。一个任务包括两个功能函数———初始化和信息处理。信息处理函数将带走事件,然后处理完它们之一后返回主循环。

函数原型:/*任务初始化函数原型*/

Typedef void(*pTaskInitFn)(unsignedchartask_id )

/* 事件处理函数原型*/

Typedef unsigned short(*pTaskEventHandlerFn)(unsignedchartask_id,

unsignedshortevent)

/* 添加任务函数原型e*/

Void osalTaskAdd(constpTaskInitFnpfnInit,constpTaskEventHandlerFn

pfnEventProcessor,constbytetaskPriority)

输入参数:pfnInit———指向任务初始化函数的指针。

pfnEventProcessor———指向任务事件处理函数的指针。

taskPriority———任务优先级,值为下列之一:

OSAL_TASK_PRIORITY_LOW:50;

OSAL_TASK_PRIORITY_MED:130;

OSAL_TASK_PRIORITY_HIGH:230。

返回:无。

6.内存管理API

该API描述了一个个简单的存储分配系统。这些函数允许动态存储分配。

1) osal_mem_alloc()

功能描述:该函数是一个简单的存储分配函数,返回指向一个缓存的指针(如果成功执行的话)。

函数原型:void *osal_mem_alloc(uint16size)

输入参数:size———被分配缓存的大小(字节数)。

返回:一个无类型(void)指针(在使用时应该指定其类型)指向被分配的新的缓存区。如果没有足够的存储空间被分配,那么将返回一个空(NULL)指针。

2) osal_mem_free()

功能描述:该函数释放被分配的存储空间,准备再一次使用。它只能释放已经被osal_mem_alloc()分配的存储空间。

函数原型:voidosal_mem_free(void *ptr)

输入参数:ptr———指向释放的存储空间。该缓存必须是已经被分配了的。

返回:无。

7.电源管理API

该API描述了OSAL 的电源管理系统。当OSAL 安全地关闭接收器和外部硬件及使处理器进入休眠模式时,该系统提供向应用/任务通报该事件的方法。

1) osal_pwrmgr_device()

功能描述:该函数在电源供电状态或电源需要改变时被调用。它可以设置设备电源管理的ON/OFF状态。这个函数应该在一个中心控制区被调用。

函数原型:voidosal_pwrmgr_device(bytepwrmgr_device)

输入参数:PWRMGR_DEVICE———改变或设置电源节能模式。

PWRMGR_ALWAYS_ON———主电源供电,无节能模式。

PWRMGR_BATTERY———打开节能模式(一般为电池供电)。

返回:无

2) osal_pwrmgr_task_state()

功能描述:该函数被每个任务调用,声明该任务是否需要节能。当任务被创建时,默认是节能模式,如果任务总是需要节能,那么不需要调用该函数。

函数原型:byteosal_pwrmgr_task_state(bytetask_id,bytestate)

输入参数:state———改变一个任务的电源模式,值为下列之一:

PWRMGR_CONSERVE:打开节能,所有的任务都认同,这是任务被初始化的默认状态。

PWRMGR_HOLD :关闭节能。

返回:返回操作结果,参数如下:

ZSUCCESS:成功。

INVALID_TASK:无效任务。

8.非易失性存储管理API

该API描述了OSAL 非易失存储系统。该系统为应用提供存储设备固定信息的方式。依照ZigBee规范,它也可以用于某些堆栈条目的固定存储,这些NV 函数被设计为可读写用户定义的如结构或队列等任意数据类型的条目。用户能读或写一个条目,也可以通过设置适当的偏移和长度读写条目的一些元素。这些API与NV 存储体没有关系,采用Flash 或EEPROM 都能实现。每个NV 条目有个唯一的ID 号,这些ID 号也有规定和限制,有些ID 值被保留,有些ID 被用在指定的堆栈或指定的平台,用户定义的条目ID 只能采用分配到的ID 值范围。条目ID 分配如下:

0x0000 :保留。

0x0001~0x0020 :OSAL。

0x0021~0x0040 :NWK。

0x0041~0x0060 :APS。

0x0061~0x0080 :安全。

0x0081~0x00A0 :ZDO。

0x00A1~0x0200 :保留。

0x0201~0x0FFF :应用。

0x1000~0xFFFF :保留。

1) osal_nv_item_init()

功能描述:在NV 中初始化一个条目。该函数在NV 中检查一个存在的条目,如果它不存在,则它被创建并用携带的数据进行初始化。在对每个条目调用osal_nv_read()或osal_nv_write()函数之前,这个函数都必须被调用。

函数原型:byteosal_nv_item_init(uint16id,uint16len,void *buf)

输入参数:id———用户定义条目ID。

len———条目长度(字节)。

*buf———条目初始化数据的指针,如果没有初始化数据,则设置为NULL。

返回:指示操作结果,参数如下:

ZSUCCESS :成功。

NV_ITEM_UNINIT :条目未被初始化。

NV_OPER_FAILED :操作失败。

2) osal_nv_read()

功能描述:从NV 读数据。该函数可以从NV 中读取整个条目或者一个条目的部分数据,读取的数据复制到*buf.缓存区。

函数原型:byteosal_nv_read(uint16id,uint16offset,uint16len,void*buf)

输入参数:id———用户定义的条目ID。

offset———条目存储偏移大小(字节)。

len———条目长度(字节)。

*buf———读入的数据。

返回:指示操作结果,参数如下:

ZSUCCESS :成功。

NV_ITEM_UNINIT :条目未被初始化。

NV_OPER_FAILED :操作失败。

3) osal_nv_write()

功能描述:写数据到NV。

函数原型:byteosal_nv_write(uint16id,uint16offset,uint16len,void*buf)

输入参数:id———用户定义的条目ID。

offset———条目存储偏移大小(字节)。

len———条目长度(字节)。

*buf———写的数据指针。

返回:指示操作结果,参数如下:

ZSUCCESS :成功。

NV_ITEM_UNINIT :条目未被初始化。

NV_OPER_FAILED :操作失败。

4) osal_offsetof()

功能描述:这个宏定义计算一个结构在内存中的偏移大小(字节)。在NV API函数中,计算补偿参数是很有用的。

函数原型:osal_offsetof(type,member)

输入参数:type———结构字节数。

member———结构成员。

转载至：《ZigBee2007/PRO 协议栈实验与实践》李文仲等