7.29. SYSTEM_TIMER

Overview

提供系统定时器使用示例方法和常见问题。

7.29.1. 应用示例

示例演示：

• sys_timer、sys_timeout、usr_timer、usr_timeout四种定时函数使用示例

example:

• 1.使用sys_timer例子在 apps/demo/demo_DevKitBoard/include/demo_config.h ，开启宏 USE_SYS_TIMER_TEST_DEMO 。

• 2.使用sys_timeout例子在 apps/demo/demo_DevKitBoard/include/demo_config.h ，开启宏 USE_SYS_TIMEROUT_TEST_DEMO 。

• 3.使用usr_timer例子在 apps/demo/demo_DevKitBoard/include/demo_config.h ，开启宏 USE_USR_TIMER_TEST_DEMO 。

• 4.使用usr_timeout例子在 apps/demo/demo_DevKitBoard/include/demo_config.h ，开启宏 USE_USR_TIMEROUT_TEST_DEMO 。

代码流程：

1. sys_timer_test()入口：

    - A）timer_id = sys_timer_add(NULL, callback_example, 5 * 1000);//注册一个定时器timer，定时时间5秒，并返回id

    - B）
      #if 0   //条件0执行修改后的定时时间2秒，条件1继续执行定时时间5秒

      printf("timer_id = %d\r\n", timer_id);      //打印分配的timer id

      #else
        if(timer_id)
        {
          printf("timer_id = %d\r\n", timer_id);
          sys_timer_modify(timer_id, 2 * 1000);   //修改timer的定时时间为2秒
        }

      #endif



    - C）每隔2秒的定时时间，则回调一次callback_example()

    - D）回调3次callback_example()后，执行sys_timer_del(timer_id);//删除timer，回调3次即删除timer

2. sys_timeout_test()入口：

   - A）timeout_id = sys_timeout_add(NULL, callback_example, 5 * 1000);//注册一个timeout，并返回id，定时时间到了自动删除timeout

   - B）#if 0   //条件0执行修改后的定时时间2秒;条件1删除定时时间为5秒的timeout
         printf("timeout_id = %d\r\n", timeout_id);

            sys_timeout_del(timeout_id);    //删除timeout，会自动删除，实际用不到该函数。

            #else
         if(timeout_id)
        {
          printf("timeout_id = %d\r\n", timeout_id);
          //sys_timeout_modify(timeout_id, 2 * 1000);  //库里暂时没有该函数，仍执行5秒定时
        }

      #endif

   - C）一旦5秒的定时时间到，仅回调一次callback_example()，自动删除timeout

3. usr_timer_test()入口:

   - A) timer_id = usr_timer_add((void* )1, callback_example, 2*1000, 1); //注册一个高精度timer，传参为1，定时时间2秒，并返回id

   - B) #if 0   //条件0执行修改后的定时时间500毫秒，条件1执行定时时间2秒
        printf("timer_id = %d\r\n", timer_id);
        #else
          if(timer_id)
         {
            printf("timer_id = %d\r\n", timer_id);
            usr_timer_modify(timer_id, 500);  //修改timer的定时时间为500毫秒
         }

         #endif

   - C )  每隔500毫秒的定时时间，则回调一次callback_example(1)

   - D）回调3次callback_example(1)后，执行sys_timer_del(timer_id); //删除timer，回调3次即删除timer

4. usr_timeout_test()入口：

   - A）timeout_id = usr_timeout_add((void* )1, callback_example, 2*1000, 1); //注册一个高精度timeout，定时时间2秒，并返回id，只回调一次

   - B）#if 0   //条件0执行修改后的定时时间500毫秒;条件1删除定时时间为2秒的timeout

         printf("timeout_id = %d\r\n", timeout_id);

         usr_timeout_del(timeout_id);    //删除timeout

            #else
         if(timeout_id)
        {
           printf("timeout_id = %d\r\n", timeout_id);
           usr_timeout_modify(timeout_id, 500);  //修改timeout的定时时间为500毫秒
        }
      #endif

  - C）一旦500毫秒的定时时间到，仅回调一次callback_example()

7.29.2. 常见问题

• sys_timer/sys_timeout与usr_timer/usr_timeout分别适用于哪些应用？

  答：sys_timer 和sys_timeout适用于在任务中执行，对时间精度要求不高的应用，usr_timer 和usr_timeout 适用于对时间精度要求高的应用。

• sys_timer/usr_timer 与 sys_timerout/usr_timerout 接口的区别？

  答：sys_timer/usr_timer 与 sys_timerout/usr_timerout 接口区别在于 timeout 接口的回调只会被调一次，也就是设定一个未来的时间， 时间到了响应之后便结束这个定时器的生命周期。

• sys_timer 与usr_timer同步异步问题

  答：sys_timer 由 systimer 线程提供时基，属于同步接口，也就是说在哪个线程 add 的 sys_timer，定时时基到了 systimer 线程会发事件通知对应 的 add 线程响应（回调函数被执行）；usr_timer 属于异步接口， add 的时候注册的回调函数将在硬件定时器中时基到时候被调用。

• 函数 usr_timer_add(void *priv, void (*func)(void *priv), u32 msec, u8 priority) 中参数 priority（优先级）的问题

  答：usr_timer 的参数 priority（优先级）为 1，系统无法进入低功耗，参数 priority（优先级）为 0，系统低功耗会忽略该节拍，节拍不会丢失，但是周期会变。

• sys_hi_timer/sys_s_hi_timer与usr_timer等同问题

  答：sys_hi_timer 等同为 priority 为 1 的 usr_timer， 在 ``include_lib/system/timer.h ``被宏定义

  ​ sys_s_hi_timer 等同为 priority 为 0 的 usr_timer，在 ``include_lib/system/timer.h ``被宏定义

7.29.3. API Reference

Functions

u16 sys_timer_add(void *priv, void (*func)(void *priv), u32 msec)

sys_timer定时扫描增加接口

Note

timer使用说明

1. 系统会进入低功耗，节拍不会丢失

2. sys_timer由systimer线程提供时基，属于同步接口，也就是说在哪个线程add的sys_timer，定时时基到了，systimer线程会发事件通知对应的add线程响应（回调函数被执行）

3. 与sys_timer_del成对使用

Parameters

• priv – 私有参数

• func – 定时扫描回调函数

• msec – 定时时间， 单位：毫秒

Returns

定时器分配的id号

u16 sys_timer_add_to_task(const char *task_name, void *priv, void (*func)(void *priv), u32 msec)

sys_timer定时扫描增加接口

Note

timer使用说明

1. 系统会进入低功耗，节拍不会丢失

2. sys_timer由systimer线程提供时基，属于同步接口，也就是说在哪个线程add的sys_timer，定时时基到了，systimer线程会发事件通知对应的add线程响应（回调函数被执行）

3. 与sys_timer_del成对使用

Parameters

• task_name – 指定任务名称

• priv – 私有参数

• func – 定时回调函数

• msec – 定时时间， 单位：毫秒

Returns

定时器分配的id号

void sys_timer_del(u16 id)

sys_timer定时扫描删除接口

Note

与sys_timer_add成对使用

Parameters

id – sys_timer_add分配的id号

u16 sys_timeout_add(void *priv, void (*func)(void *priv), u32 msec)

sys_timer超时增加接口

Note

timer使用说明

1. 系统会进入低功耗，节拍不会丢失

2. sys_timeout由systimer线程提供时基，属于同步接口，也就是说在哪个线程add的sys_timeout，定时时基到了，systimer线程会发事件通知对应的add线程响应（回调函数被执行）

3. timeout回调只会被执行一次

4. 与sys_timeout_del成对使用

Parameters

• priv – 私有参数

• func – 超时扫描回调函数

• msec – 超时时间， 单位：毫秒

Returns

定时器分配的id号

u16 sys_timeout_add_to_task(const char *task_name, void *priv, void (*func)(void *priv), u32 msec)

sys_timer超时增加接口

Note

timer使用说明

1. 系统会进入低功耗，节拍不会丢失

2. sys_timeout由systimer线程提供时基，属于同步接口，也就是说在哪个线程add的sys_timeout，定时时基到了,systimer线程会发事件通知对应的add线程响应（回调函数被执行）

3. timeout回调只会被执行一次

4. 与sys_timeout_del成对使用

Parameters

• task_name – 指定任务名称

• priv – 私有参数

• func – 超时回调函数

• msec – 超时时间， 单位：毫秒

Returns

定时器分配的id号

void sys_timeout_del(u16 id)

sys_timer超时删除接口

Note

与sys_timeout_add成对使用

Parameters

id – sys_timeout_add分配的id号

void sys_timer_re_run(u16 id)

sys_timer定时器重置

Note

在定时时间到之前进行重置之后重新计时,sys_timeout定时到之后会被删除,re_run无效

Parameters

id – sys_timer和分sys_timeout配的id号

void sys_timer_set_user_data(u16 id, void *priv)

sys_timer定时器设置私有参数

Parameters

• id – sys_timer分配的id号

• priv – 私有参数

void *sys_timer_get_user_data(u16 id)

sys_timer定时器获取私有参数

Note

如果有通过sys_timer_set_user_data重新设置私有参数,则返回的是设置后的私有参数

Parameters

id – sys_timer分配的id号

Returns

返回add时的私有参数

int sys_timer_modify(u16 id, u32 msec)

sys_timer修改定时扫描时间接口

Parameters

• id – sys_timer_add和sys_timeout_add分配的id号

• msec – 定时时间， 单位：毫秒

Returns

0

int sys_usec_timer_add(void *priv, void (*func)(void *priv), u32 usec, u8 call_in_irq, u8 once)

微秒级重复定时器添加

Note

微秒级定时器同一时间只能运行一个

Parameters

• priv – 私有参数

• func – 回调函数

• usec – 定时时间， 单位：微秒

• call_in_irq – 回调函数是否在中断里面执行

• once – 是否只运行一次

Returns

定时器分配的id号

void sys_usec_timer_set(int id, u32 usec)

微秒级定时器的定时时间修改

Parameters

• id – sys_usec_timer_add分配的id号

• usec – 定时时间， 单位：微秒

void sys_usec_timer_del(int id)

微秒级定时器删除接口

Note

与sys_usec_timer_add成对使用

Parameters

id – sys_usec_timer_add分配的id号

u16 usr_timer_add(void *priv, void (*func)(void *priv), u32 msec, u8 priority)

usr_timer定时扫描增加接口

Note

timer使用说明

1. usr_timer的参数priority（优先级）为1，使用该类定时器，系统无法进入低功耗

2. usr_timer的参数priority（优先级）为0，使用该类定时器，系统低功耗会忽略该节拍，节拍不会丢失，但是周期会变

3. usr_timer属于异步接口， add的时候注册的扫描函数将在硬件定时器中时基到时候被调用。

4. 对应释放接口usr_timer_del

Parameters

• priv – 私有参数

• func – 定时扫描回调函数

• msec – 定时时间， 单位：毫秒

• priority – 优先级,范围：0/1

Returns

定时器分配的id号

u16 usr_timeout_add(void *priv, void (*func)(void *priv), u32 msec, u8 priority)

usr_timer超时增加接口

Note

timer使用说明

1. usr_timeout的参数priority（优先级）为1，使用该类定时器，系统无法进入低功耗

2. usr_timeout的参数priority（优先级）为0，使用该类定时器，系统低功耗会忽略该节拍，节拍不会丢失，但是周期会变

3. usr_timeout属于异步接口， add的时候注册的扫描函数将在硬件定时器中时基到时候被调用。

4. 对应释放接口usr_timerout_del

5. timeout回调只会被执行一次

Parameters

• priv – 私有参数

• func – 超时回调函数

• msec – 超时时间， 单位：毫秒

• priority – 优先级,范围：0/1

Returns

定时器分配的id号

int usr_timer_modify(u16 id, u32 msec)

usr_timer修改定时扫描时间接口

Parameters

• id – usr_timer_add时分配的id号

• msec – 定时时间， 单位：毫秒

Returns

0

int usr_timeout_modify(u16 id, u32 msec)

usr_timeout修改超时时间接口

Parameters

• id – usr_timeout_add时分配的id号

• msec – 超时时间， 单位：毫秒

Returns

0

void usr_timer_del(u16 id)

usr_timer删除接口

Note

注意与usr_timer_add成对使用

Parameters

id – usr_timer_add时分配的id号

void usr_timeout_del(u16 id)

usr_timeout删除接口

Note

注意与usr_timeout_add成对使用

Parameters

id – usr_timerout_add时分配的id号

void usr_timer_dump(void)

usr_time输出调试信息

Note

调试时可用，将输出所有被add定时器的id及其时间(msec)

---