ZigBee学习之7——OSAL(操作系统抽象层)API解读

根据Z-Stack1.4.3-1.2.0中OSAL API_F8W-2003-0002_.pdf文档翻译。

Z-Stack1.4.3及以后的版本中引入了一个OS的概念，把应用层和堆栈层进行了分离，但是这个操作系统并不是时实的操作系统，所以有兴趣的话还可以将其改为时实的操作系统，或者用其他开源的实时操作系统取代，比如USOS，呵呵。我将这个OS的API文档进行了一定的翻译，当然所谓一定，就是说有的地方没有翻译出来罗，要么是我不会的，要么就是我觉得没必要翻译的东西，总之，提供给各位一个参考，最好是对照原文档来阅读拉。

没接触过操作系统，也是第一次搞Zigbee，错误的地方还请各位多多指正。

OSAL(操作系统抽象层) API[OSAL API_F8W-2003-0002_.pdf]

这个层次主要是将Z-Stack软件组件从特殊的处理过程相分离，将其保护起来。一般来说提供如下几个功能：

·                     任务的注册、初始化、开始

·                     任务间的消息交换

·                     任务同步

·                     中断处理

·                     时间管理

·                     内存分配

消息管理API

消息管理API提供任务（或处理单元）间的消息交换（比如中断服务事务，控制循环中的函数调用）。这些API能用来允许任务分配和取消分配的消息缓存，发送对其他任务的命令消息，接受应答消息。

byte *osal_msg_allocate(uint16 len)

分配一个消息缓存，随后调用它的任务/函数将填充消息并调用osal_msg_send()将消息发送给其他任务。

参数：消息长度；

返回值：指向消息缓存的指针，失败则为NULL。

byte osal_msg_deallocate(byte *msg_ptr)

任务接收完消息后用来释放分配的消息缓存。

参数：要释放的消息缓存；

返回值：ZSUCCESS             - 成功

    INVALID_MSG_POINTER     - 无效的消息指针

    MSG_BUFFER_NOT_AVAIL        - 缓存正在队列（queued）

byte osal_msg_send(byte destination_task,byte *msg_ptr)

向其他任务或处理单元发送命令或数据消息。目标任务ID域必须有效的系统任务。任务ID由开始任务时的osal_creat_task()分配。此函数将在目标任务事件列表中设置SYS_EVENT_MSG事件。

参数：  destination_task    - 目标任务ID；

    msg_ptr     - 指向包含消息的消息缓存的指针；

返回值：ZSUCCESS             - 成功

    INVALID_MSG_POINTER     - 无效的消息指针

    INVALID_TASK            - 目标任务不正确

byte *osal_msg_receive(byte task_id)

提取接收到的命令消息，在处理完消息后必须用osal_msg_deallocate()释放消息缓存。

参数：  task_id     - 调用者的任务ID（即消息发往的目标任务）；

返回值：指向包含消息的一段缓存，若没有接收到消息则为NULL。

任务同步API

允许任务等待事件发生并在等待时返回控制信息。用来为任务设置事件

byte osal_set_event( byte task_id, UINT16 event_flag )

为任务设置事件标志。

参数：  task_id     - 将设置事件的任务ID；

    event_flag      - 2字节的位图，其中每位指定了一个事件。只有一个系统事件（SYSTEM_EVENT_MSG），其余的事件/位由接收任务指定；

返回值：ZSUCCESS             - 成功

    INVALID_TASK            - 任务不正确

时钟管理API

这些API允许内部（Z-Stack）任务和外部（应用层）任务用时钟。API提供启动，停止时钟的函数。时钟能被设置成1ms的增量。

byte osal_start_timer(UINT16 event_id, UINT16 timeout_value)

启动时钟。当时钟超时，相关的事件位将设置。事件将设置在调用此函数的任务中。

参数：  event_id        - 用户定义的事件位，当时钟超时调用任务将被通知；

    timeout_value       - 超时时间（ms）；

返回值：ZSUCCESS             - 成功

    NO_TIMER_AVAILABLE      - 失败

byte osal_start_timerEx( byte taskID, UINT16 event_id, UINT16 timeout_value)

在前一个函数的基础上调用者可以为别的任务设置时钟。

参数：  taskID          - 超时时接收事件的任务的任务ID；

    event_id        - 用户定义的事件位，当时钟超时调用任务将被通知；

    timeout_value       - 超时时间（ms）；

返回值：ZSUCCESS             - 成功

    NO_TIMER_AVAILABLE      - 失败

byte osal_stop_timer( UINT16 event_id )

byte osal_stop_timerEx( byte task_id, UINT16 event_id )

指定停止那个任务的时钟。

参数：  task_id     - 要停止时钟的任务；

    event_id        - 要停止的时钟的id；

返回值：ZSUCCESS             - 成功

    INVALID_EVENT_ID        - 失败

uint32 osal_GetSystemClock( void )

读取系统时钟（ms）

中断管理API

这些API提供任务和外部中断的接口。API中的函数允许任务和每个中断的服务程序相关联，可以允许和禁止中断，在服务程序中可以为其他任务设置事件。

byte osal_int_enable( byte interrupt_id )

byte osal_int_disable( byte interrupt_id )

参数：  interrupt_id        - 要允许的中断；

返回值：ZSUCCESS             - 成功

    INVALID_INTERRUPT_ID        - 不可用的中断

任务管理API

添加和管理OSAL系统任务的API，这个应该是系统层的关键API吧。每个任务由初始化函数，事件处理函数构成。OSAL调用osalInitTasks() 来初始化任务并利用任务表来为每个任务调用事件处理。

byte osal_init_system( void )

初始化OSAL系统。需要在调用其他OSAL函数前调用。

void osal_start_system( void )

这是任务系统的主循环函数，它将监视所有任务事件并负责调用事件处理函数，如果特定任务的事件发生，它将调用此任务的事件处理函数来处理事件，其余的事件将返回主循环。如果没有事件发生则使处理器进入睡眠模式。

注意在这个版本中已经不支持osalTaskAdd () 了。

内存管理API

void *osal_mem_alloc( uint16 size )

参数：  size                - 要分配的字节数；

返回值：指向新分配空间的VOID指针，如果失败则返回指向NULL的指针。

void osal_mem_free( void *ptr )

和前一个函数配对，用来释放其分配的内存空间。

参数：  ptr             - 指向已分配的内存的指针；

电源管理API

系统为应用/协议栈提供了一个方式用来通知OSAL什么时候可以安全关闭接收器或外部设备，什么时候能进入休眠。

void osal_pwrmgr_state( byte pwrmgr_device )

设置器件电源管理的全局开关状态。应该在中心控制实体（如ZDO）中调用此函数。

参数：  pwrmgr_device               - 改变或设置电源节约模式，

        PWRMGR_ALWAYS_ON        - 没有电源节约模式

        PWRMGR_BATTERY      - 打开电源节约模式

byte osal_pwrmgr_task_state( byte task_id, byte state )

每个任务通过调用这个函数来声明是否需要节约电源。任务调用这个函数来进入节能模式或者保持节能模式。默认每个任务创建后其电源模式都为节能模式。

参数：  state                   - 改变一个任务的电源模式，

        PWRMGR_CONSERVE     - 打开节能模式

        PWRMGR_HOLD         - 关闭节能模式

返回值：ZSUCCESS             - 成功

    INVALID_TASK            - 不可用的任务

非易失储存器（NV）管理API

系统为应用提供了将信息持久保存在器件储存器中的方式。NV函数用来读写用户定义的具有独特数据字节的数据，比如结构体或数组。用户能够读写整个数据或者设置合适的偏移和长度来读取数据中某个元素。NV API独立于非易失性储存媒介，能用FLASH或EEPROM来实现。

每个NV条目都有自己独立的ID，对于应用，ID值有特定的范围。如果你的应用创建了自己的NV条目，就必须从应用范围中选择一个ID。

值          用户

0x0000          保留

0x0001-0x0020       OSAL

0x0021-0x0040       NWK

0x0041-0x0060       APS

0x0061-0x0080       安全

0x0081-0x00A0       ZDO

0x00A1-0x0200       保留

0x0201-0x0FFF       应用

0x1000-0xFFFF       保留

注意1、这些API的调用可能会花费几毫秒的时候，特别是在写操作的时候，而且中断也会被禁止几毫秒。

2、尽量少执行NV写操作，因为它既费时又耗能。

3、如果一个或多个NV条目的数据结构发生改变，特别是在升级Z-Stack版本的时候，最好搽除并重新初始化NV储存器。

byte osal_nv_item_init( uint16 id, uint16 len, void *buf )

检查存在的NV条目，如果不存在则用传入函数的数据创建和初始化。在调用osal_nv_read() 或者osal_nv_write()前必须调用这个函数。

参数：  id              - 用户定义的条目ID

    len             - 以字节为单位的条目长度

    *buf                - 指向条目初始化数据，如果没有则设为NULL

返回值：ZSUCCESS             - 成功

    NV_ITEM_UNINIT      - 成功，但是条目不存在

    NV_OPER_FAILED      - 失败

byte osal_nv_read( uint16 id, uint16 offset, uint16 len, void *buf )

从非易失性储存中读数据到*buf中

byte osal_nv_write( uint16 id, uint16 offset, uint16 len, void *buf )

返回值：ZSUCCESS             - 成功

    NV_ITEM_UNINIT      - 成功，但是条目不存在

    NV_OPER_FAILED      - 失败

osal_offsetof(type, member)

用来计算结构中特定成员的内存偏移量的宏。

参数：  type                - 结构类型

    member              - 结构成员