OSAL API

一、信息管理API

1. osal_msg_allocate( )函数原型：任务是分配一个信息缓冲区，当任务调用或函数被调用时，该空间被信息填充或调用信息发送函数osal_msg_send() 发送缓冲空间的信息到其他任务，若该缓冲空间不能被分配，则设置msg_ptr=NULL空；

         uint8 *osal_msg_allocate( uint16 len )，返回的是指针，若返回为空，则该信息缓存空间分配失败。

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

2.osal_msg_deallocate( ) 信息处理分配缓存。该函数通过一个任务调用后完成处理一个接收的信息。

        uint8 osal_msg_deallocate( uint8 *msg_ptr )

msg_ptr指向需要处理分配信息缓存的指针

成功；无效的信息指针；缓存被排队。

 

 

 3. osal_msg_send( )一个任务发送一个命令或数据信息到其他任务或处理元素中。

uint8 osal_msg_send(uint8 destination_task, uint8 *msg_ptr )

 

4.osal_msg_receive( ) 任务接受一个命令信息调用该函数

           uint8 *osal_msg_receive(uint8 task_id )

Return value is a pointer to a buffer containing the message or NULL if there is no received message.

5. osal_msg_find( )

osal_event_hdr_t *osal_msg_find(uint8 task_id, uint8 event)

This function searches for an existing OSAL message matching the task_id and event parameters

二、任务同步API：允许一个任务等待某个事件的发生并返回等待期间的控制

作用：set events for a task and notify the task once any event is set

1.osal_set_event( ) ：set the event flags for a task

uint8 osal_set_event(uint8 task_id, uint16 event_flag ) 其中event_flag is a 2-byte bitmap ，每位对应一个事件
 There is only one system event (SYS_EVENT_MSG), the rest of the events/bits are defined by the receiving task

三、时间管理API

该API允许定时器被内部和外部任务使用，具有开启和停止一个定时器的功能，，该定时器能用1毫秒的增量设置。

1.osal_start_timerEx( )启动定时器

uint8 osal_start_timerEx( uint8 taskID, uint16 event_id, uint16 timeout_value);

 

2. osal_start_reload_timer( )

uint8 osal_start_reload_timer( uint8 taskID, uint16 event_id, uint16 timeout_value );

  设置 set an event bit and 自动重载计数

3.osal_stop_timerEx( )停止已经被启动的定时器

uint8 osal_stop_timerEx( uint8 task_id, uint16 event_id );

4.osal_GetSystemClock( ) 读取系统时钟

uint32 osal_GetSystemClock( void );

返回值：The system clock in milliseconds.

四、中断管理API:是任务和外部中断的接口，允许一个任务为每个中断分配指定的服务程序

1. osal_int_enable( ) 允许中断

uint8 osal_int_enable( uint8 interrupt_id )

2. osal_int_disable( )禁止某个中断

  uint8 osal_int_disable( uint8 interrupt_id )

 

 五、任务管理API：用于添加和管理osal中的任务，每个任务都由初始化函数和事件处理函数组成。

OSAL calls  osalInitTasks() [application supplied] to initialize the tasks and OSAL uses a task table (const  pTaskEventHandlerFn tasksArr[]) to call the event processor for each task (also application supplied).

Example of a task table implementation: 
 
const pTaskEventHandlerFn tasksArr[] =  
{ 
  macEventLoop, 
  nwk_event_loop, 
  Hal_ProcessEvent, 
  MT_ProcessEvent, 
  APS_event_loop, 
  ZDApp_event_loop, 
};  
const uint8 tasksCnt = sizeof( tasksArr ) / sizeof( tasksArr[0] ); 计算数组元素个数

1.osal_init_system( )初始化osal系统：在启动任何一个OSAL之前必须被调用

uint8 osal_init_system( void )返回值为“SUCCESS”

2. osal_start_system( ) 任务系统的主循环函数

void osal_start_system( void )

3.osal_run_system( ) ：void osal_run_system( void )

4.osal_self( )返回当前运行任务的ID号：uint8 osal_self( void )

 六、内存管理API：简单的存储分配系统。允许动态存储分配

1.osal_mem_alloc( ) 一简单存储分配函数，如果成功执行则返回指向一个缓存的指针

void *osal_mem_alloc( uint16 size );一个无类型指针指向被分配的新的缓存区

2. osal_mem_free( )释放被分配的存储空间以备再一次使用，只能释放被 osal_mem_alloc()分配的存储空间

void osal_mem_free( void *ptr );

七、电源管理API：当OSPL安全关闭接收器和外部硬件，并使处理器进入休眠模时，提供向应用/任务通报该事件的方法

osal_pwrmgr_device()， osal_pwrmgr_task_state( PWRMGR_HOLD )

1. osal_pwrmgr_init( ) ：void osal_pwrmgr_init( void );不要调用此函数，因为已经在osal_init_system()中调用了

2. osal_pwrmgr_powerconserve( ) ：void osal_pwrmgr_powerconserve( void );进入掉电模式

Do not call this function, it is already called in the OSAL main loop [osal_start_system()].

3.osal_pwrmgr_device( ) ：void osal_pwrmgr_device( uint8 pwrmgr_device );

函数在电源供电状态或者电源需要改变时调用，可以设置设备电源管理的ON/OFF状态，这函数应该在一个中心控制区别调用比如ZDO.

4.osal_pwrmgr_task_state( )：uint8 osal_pwrmgr_task_state(uint8 task_id, uint8 state );

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

state:

返回值

八、非易失性存储管理API：Non-Volatile Memory API

NV 函数被设计为可以读写用户定义的如结构或队列等任意的数据类型组成的条目，flash or EEPROM

每个NV条目有个唯一的ID号，但都有规定和限制

 1.osal_nv_item_init( )：初始化一条目。该函数检查一存在的条目，若它不存在，则它被创建并用携带的数据进行初始化，在对每个条目调用 osal_nv_read() or osal_nv_write()之前，这个函数必须被调用

uint8 osal_nv_item_init( uint16 id, uint16 len, void *buf );条目初始化数据的指针

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

从nv读取数据。read an entire item from NV or an element of an item by indexing into the item with an offset。读取的数据复制到*buf缓冲区

 

 3.osal_nv_write( )：写数据到NV。uint8 osal_nv_write( uint16 id, uint16 offset, uint16 len, void *buf );

write an entire item to NV or an element of an item by indexing into the item with an offset

4.osal_nv_delete( )：从nv中删除条目。 uint8 osal_nv_delete( uint16 id, uint16 len );

该函数检查一存在的条目，若它存在，并且它的长度matches the length provided in the function call, 条目将从nv中移除。 

5.osal_nv_item_len( )： uint16 osal_nv_item_len( uint16 id );在NV中得到一个条目的长度

6.osal_offsetof( )：这个宏定义计算一个结构在内存中偏移的大小（字节） osal_offsetof(type, member)

 calculating the offset parameter 在NV API 函数中很有用。

九、简单的NV存储API：

Like the OSAL NV memory system, the Simple NV memory system provides a way for applications to store information into the device’s memory persistently. On the other hand, unlike the OSAL NV memory system, the Simple NV memory system provides much simpler API to drive the application code size and  the stack code size down as well as the code size of the 
OSAL Simple NV system implementation. 用户可以读写整个条目但不能读写条目中的某部分。

 1.osal_snv_read( )： uint8 osal_snv_read( osalSnvId_t id, osalSnvLen_t len, void *pBuf );从nv中读取数据

 2.osal_snv_write( )：写数据到Nv: uint8 osal_snv_write( osalSnvId_t id, osalSnvLen_t len, void *pBuf );

 十、OSAL时钟系统：为设备保持日期和时间提供一种方法，This system will keep the number of seconds since 0 hrs, 0 minutes, 0 seconds on 1 January 2000 UTC，两种数据类型或结构被定义在 OSAL_Clock.h中

typedef uint32 UTCTime; // To be used with  ， In addition, this feature does not maintain time for sleeping devices
typedef struct 
{ 
  uint8 seconds;  // 0-59 
  uint8 minutes;  // 0-59 
  uint8 hour;     // 0-23 
  uint8 day;      // 0-30 
  uint8 month;    // 0-11 
  uint16 year;    // 2000+ 
} UTCTimeStruct;

 1.osalTimeUpdate( )：从 osal_run_system()运行来更新时间， void osalTimeUpdate( void );

此函数reads the number of MAC 320usec ticks to maintain the OSAL Clock time. Do not call this function anywhere else

2.osal_setClock( ) ：初始化设备时间。 void osal_setClock( UTCTime newTime )

3.osal_getClock( )：调用这个函数来获取设备的当前时间。UTCTime osal_getClock( void );

4.osal_ConvertUTCTime( ) ：将UTCTime转换成 UTCTimeStruct的函数

void osal_ConvertUTCTime( UTCTimeStruct * tm, UTCTime secTime );

5.osal_ConvertUTCSecs( ) ：将UTCTimeStruct转换成UTCTime 的函数

UTCTime osal_ConvertUTCSecs( UTCTimeStruct * tm );

十一、OSAL Misc杂项：

This section describes miscellaneous OSAL functions that do not fit into the previous OSAL categories

描述不适合先前OSAL类别的多样化OSAL函数。

1.osal_rand( ) ：返回一个16位的随机数uint16 osal_rand( void );

2. osal_memcmp( ) ：比较内存部分。

uint8 osal_memcmp( const void GENERIC *src1, const void GENERIC *src2, unsigned int len );

返回值：TRUE - same, FALSE - different

3.osal_memset( )：void *osal_memset( void *dest, uint8 value, int len );

功能Sets a buffer to a specific value，返回值Pointer to where in the buffer this function stopped

4.osal_memcpy( ) ：void *osal_memcpy( void *dst, const void GENERIC *src, unsigned int len );

功能Copies one buffer to another buffer，返回Pointer to end of destination buffer