ZigBee_CC2530_09H_API函数

  Zstack协议栈依靠协议栈内部的OS(即OSAL)才能运行起来，OSAL提供的服务和管理包括：信息管理、任务同步、时间管理、中断管理、任务管理、内存管理、电源管理以及非易失存储管理。

1. 信息管理API

  信息管理API为任务和处理单元之间的信息交换提供了一种具有不同处理环境的机制(例如，在一个控制循环中调用中断服务常规程序或函数)。这个API中国的函数可以使任务分配或回收信息缓冲区，给其他任务发送任务信息以及接受回复信息。

1.1 osal_msg_allocate()

  这个函数被一个任务调用去分配一个信息缓冲，这个任务/函数将填充这个信息并且调用osal_msg_send()发送消息到另一个任务中。函数原型如下：

    uint8 *osal_msg_allocate( uint16 len );

  参数描述：

    len是信息的长度。

  返回值：返回值是指向一个信息分配的缓冲区的指针。一个空值的返回表明信息分配操作失败。

1.2 osal_msg_deallocate()

  这个函数用来回收一个信息缓冲区，在完成处理一个接受信息后这个函数被一个任务(或处理机单元)低啊用。函数原型如下：

    uint8 osal_msg_deallocate(byte *msg_ptr);

  参数描述：

msg_ptr是指向必须回收的信息缓冲的指针。

  返回值：返回值指示了操作的结果。

ZSUCCESS：分配成功；

INVALID_MSG_POINTER：无效的信息指针；

MSG_BUFFER_NOT_AVAIL：缓冲区队列。

1.3 osal_msg_send()

  这个函数的功能是被一个任务调用，给另一个任务或者处理单元发送命令或数据信息。函数原型如下：

    uint8 osal_msg_send( byte destination_task , byte *msg_ptr);

  参数描述：

destination_task是接收信息任务的ID。

msg_ptr是指向必须包含信息的缓冲区的指针。msg_ptr必须执行osal_msg_allocate()分配的一个有效缓冲区。

  返回值：返回值是一个字节，表明操作的结果。

ZSUCCESS：分配成功；

INVALID_MSG_POINTER：无效的信息指针；

INVALID_TASK：destination_task是无效的。

1.4 osal_msg_receive()

  此函数被一个任务调用来检索一条已经收到的命令信息。调用osal_msg_receive()处理信息后，必须回收信息缓冲区。函数原型如下：

    uint8 *osal_msg_receive( byte task_id);

  参数描述：task_id是调用任务(信息指定的)的标识符。

  返回值：返回值是一个指向包含该信息的缓冲区的指针，如果没有已接收的信息，返回值为空(NULL)。

2. 任务同步API

  任务同步API使得任务等待事件发送，并在等待期间返回控制。这个API中的函数可以用来为一个任务设置事件，无论设置了什么事件都通知任务。

  通过osal_set_event()这个函数调用，为一个任务设置事件的标志。其函数原型如下：

    uint8 osal_set_event( byte task_id , UINT16 event_flag );

  参数描述：

task_id是设置事件的任务的标识符。

event_flag是两个字节的位图且每个位详述了一个事件。这仅有一个系统事件(SYS_EVENT_MSG),其余事件/位都是通过接收任务来规定的。

  返回值：返回值指示操作的结果。

ZSUCCESS：成功；

INVALID_TASK：无效事件；

3. 定时器管理API

  定时器管理API使Zstack内部的任务和外部的应用层任务都可以使用定时器。API提供了启动和停止一个定时器的功能，这个定时器可设定递增的一毫秒。

3.1 osal_start_timer()

  启动一个定时器时调用此函数。当定时器终止时，给定的事件位将设置。这个事件通过osal_start_timer()函数调用，将在任务中设置。函数原型如下：

    uint8 osal_start_timer( UINT16 event_id , UINT16 timeout_value);

  参数描述：

event_id是用户确定事件的ID。当定时器终止时，该事件将被触发。

timeout_value指定时器事件设置之前的时长(以毫秒为单位)。

  返回值：返回值指示操作的结果。

ZSUCCESS：成功；

NO_TIMER_AVAILABLE：没有能够启动定时器；

3.2 osal_start_timerEx()   类似于osal_start_timer()，增加了taskID参数。允许访问这个调用程序为另一个任务设置定时器。函数原型如下：

    uint8 osal_start_timerEx( byte taskID , UINT16 event_id , UINT16 timerout_value );

  参数描述：

taskID是定时器终止时，获取该事件任务的ID。

event_id是用户确定事件的ID。当定时器终止时，该事件将被触发。

timeout_value指定时器事件设置之前的时长(以毫秒为单位)。

  返回值：返回值指示操作的结果。

ZSUCCESS：成功；

NO_TIMER_AVAILABLE：没有能够启动定时器；

3.3 osal_stop_timer()

    此函数用来停止一个已启动的定时器，如果成功，函数将取消定时器并阻止设置调用程序中与定时器有关的时间。使用osal_stop_timer()函数，意味着调用osal_stop_timer()的任务中定时器正在运行。函数原型如下：

    uint8 osal_stop_timer( UINT16 event_id );

  参数描述：

event_id是要停止的计时器的标识符。

  返回值：返回值指示操作的结果。

ZSUCCESS：关闭定时器成功；

INVALID_EVENT_ID：无效事件；

3.3 osal_stop_timerEx()   此函数功能是在不同的任务中中止定时器的，与osal_stop_timer()函数类似，只是指明了任务ID。函数原型如下：

    uint8 osal_stop_timerEx( byte task_id , UINT16 event_id );

  参数描述：

task_id：停止定时器所在的任务ID。

event_id：要停止的计时器的标识符。

  返回值：返回值指示操作的结果。

ZSUCCESS：关闭定时器成功；

INVALID_EVENT_ID：无效事件；

3.5 osal_GetSystemClock()

  此函数功能为读取系统时钟。函数原型如下：

    uint8 osal_GetSystemClock( void );

  返回值为以毫秒为单位的系统时钟。
4. 中断管理API

  中断管理API可以使一个任务与外部中断互相交流。API中的函数允许和每个中断去联络一个具体的服务流程。中断可以启用或禁用，在服务例程内部，可以为其他任务设置事件。

4.1 osal_int_enable()

  此函数的功能是启用一个中断，中断一旦启用将调用与该中断相联系的服务例程。函数原型如下：

    uint8 osal_int_enable( byte interrupt_id );

  参数描述：

interrupt_id：指明要启用的中断。

  返回值：返回值指示操作的结果。

ZSUCCESS：开启中断成功；

INVALID_INTERRUPT_ID：无效中断；

4.2 osal_int_disable()

  此函数的功能是禁用一个中断，当禁用一个中断时，与该中断相联系的服务例程将不被调用。函数原型如下：

    uint8 osal_int_enable( byte interrupt_id );

  参数描述：

interrupt_id：指明要禁用的中断。

  返回值：返回值指示操作的结果。

ZSUCCESS：关闭中断成功；

INVALID_INTERRUPT_ID：无效中断；

5. 任务管理API

  在OSAL系统中，API常用语添加和管理任务。每个任务由初始化函数和时间处理函数组成。

5.1 osal_init_system()

  此函数功能为初始化OSAL系统。在使用任何其他OSAL函数之前必须先调用此函数启动OSAL系统。函数原型为：

    uint8 osal_init_system( void );

  参数描述：

无。

  返回值：返回值指示操作的结果。

ZSUCCESS：初始OSAL系统成功；

5.2 osal_start_system()

  此函数是任务系统中的主循环函数。它将仔细检查所有的任务事件，并且为含有该事件的任务调用任务事件处理函数。如果有特定任务事件，这个函数将为该任务调用事件处理例程来处理事件。相应任务的事件处理例程一次处理一个事件。一个事件被处理后，剩余事件将等待下一次循环。如果没有时间，这个函数时处理器程序处于睡眠模式。函数原型为：

    uint8 osal_start_system( void );

  参数描述：

无。

  返回值：返回值指示操作的结果。

ZSUCCESS：成功；

6. 内存管理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

  当安全关闭接收器或外部硬件时，电源管理API为应用程序或任务提供了告知OSAL的方法，使处理器转入睡眠状态。

  电源管理API有2个函数：osal_pwrmgr_device()和osal_pwrmgr_task_state()。第一个函数时设置设备的模式；第二个为电源状态管理。

7.1 osal_pwrmgr_device()

  当升高电源或需要改变电源时(例如：电池支持的协调器)，这个函数应有中心控制实体(比如ZDO)调用。函数原型如下：

    void osal_pwrmgr_device( byte pwrmgr_device);

  参数描述：

pwrmgr_device：改变和设置电源的节省模式。

PWRMGR_ALWAYS_ON：没有省电模式，设备可能使用主电源供电。

PWRMGR_BATTERY：打开省电模式。

  返回值：

             无。

7.2 osal_pwrmgr_task_state()

  每个任务都将调用此函数。此函数的功能是用来表决是否需要OSAL电源保护或推迟电源保护。当一个任务被创建时，默认情况下电源状态设置为保护模式。如果该任务一直想保护电源，就不必调用该函数。函数原型如下：

    void osal_pwrmgr_task_state( bytetask_id , byte state);

  参数描述：

state：改变一个任务的电源状态。

PWRMGR_CONSERVE：打开省电模式，所有事件必须允许。事件初始化时，此状态位默认状态。

PWRMGR_HOLD：关闭省电模式。

  返回值：

             ZSUCCESS：成功。

INVALID_TASK：无效事件。

8.非易失性存储管理API

  非易失性存储器API为应用程序提供了一种吧信息永久保存到设备内存的方法。它还能用于把Zigbee规范要求的某些项目永久保存到协议栈。NV函数的功能是读写任意数据类型的用户自定义项目，比如结构体和数组。用户能通过设置合适的偏移和长度来读写一个整体的项目或元素。API独立于NV存储介质，并且能用于实现闪存或EEPROM。

  每个易失性的项目都仅有一个ID，当一些ID由栈或平台保留或运用时，应用程序中有特定的一系列ID值。加入应用程序创建自己的易失性项目，它必须从应用范围的值内选择一个标识符。如表所示：

值 使用者 0x0000 保留 0x0001-0x0020 操作系统抽象层 0x0021-0x0040 网络层 0x0041-0x0060 应用支持子层 0x0061-0x0080 安全 0x0081-0x00A0 Zigbee设备对象 0x00A1-0x0200 保留 0x0201-0x0FFF 应用程序 0x1000-0xFFFF 保留   运用API时需要注意以下几个方面：

有一些模块化调用函数，操作系统可能需要较短的时间来完成(例如几毫秒的时间)，尤其是对NV写入操作。

尽量不要频繁地执行NV写入操作。

结构体中一个或多个NV项目改变，尤其是从一个Zstack版本升级至另一个版本时，必须擦除和重新初始化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：初始化数据指针。如没初始化数据，则设置为空。

  返回值：返回值指示操作的结果。

ZSUCCESS：成功；

NV_ITEM_UNINIT：对象没初始化；

NV_OPER_FAILED：操作失败。

8.2 osal_nv_read()

  此函数用于从NV中读出数据，用于从NV中带用偏移的索引指向的项目中读出整个项目或一个元素，读出数据复制到*buf中。函数原型如下：

    uint8 osal_nv_read( uint16 id , uint16 offset ,uint16 len , void *buf);

  参数描述：

id：用户自定义项的ID。

offset：以字节为单位到项目的存储偏移量

len：项目字节长度。

*buf：数据读取到缓冲区。

  返回值：返回值指示操作的结果。

ZSUCCESS：成功；

NV_ITEM_UNINIT：对象没初始化；

NV_OPER_FAILED：操作失败。

8.3 osal_nv_write()

  此函数用于写入数据到NV中，用于从NV中带用偏移的索引指向的项目中写入整到整个NV项目中。函数原型如下：

    uint8 osal_nv_write( uint16 id , uint16 offset ,uint16 len , void *buf);

  参数描述：

id：用户自定义项的ID。

offset：以字节为单位到项目的存储偏移量

len：项目字节长度。

*buf：数据写入到缓冲区。

  返回值：返回值指示操作的结果。

ZSUCCESS：成功；

NV_ITEM_UNINIT：对象没初始化；

NV_OPER_FAILED：操作失败。

8.4 osal_offsetof()

  此函数用于计算一个结构体内元素的偏移量，以字节为单位。用它来计算NV API函数使用的参数的偏移量。函数原型如下：

    uint8 osal_offsetof( type , member);

  参数描述：

              type：结构体类型。

             member：结构体成员

  返回值：

            无。