概述

本文介绍如何在 睿擎工业开发平台 中创建并运行 硬件定时器（HWTIMER） 示例工程，基于 RT-Thread 设备驱动框架，驱动 GD32H77D 片内定时器外设，演示定时器设备查找、定时模式配置、超时回调注册与周期定时的完整流程。

硬件定时器框架

硬件定时器（HWTIMER）框架是 RT-Thread 中管理片上定时器资源的设备驱动模型，提供定时模式设置（单次 / 周期）、 超时回调注册、超时时间设置与定时停止等标准化接口。超时时间以 秒 + 微秒 精度配置，定时精度可达微秒级， 适用于精确定时、周期采样与定时事件触发等场景。

查询配置树获取硬件定时器资源

根据 GD32H77D 配置树可知：

• GD32H77D 片内集成多路硬件定时器，本示例使用 hwtimer30，用户可在配置树文件中按实际硬件选择其他实例；
• 定时精度可达微秒级，超时周期可通过命令参数动态配置。

构建与烧录

创建工程点击展开

1. 依次点击 “文件” -> “新建” -> "RT-Thread RuiChing App 项目"。

   

2. 在弹出新建向导中选择 开发版 、BSP: 、示例 、 调试器/下载器。选择好之后点击 “完成”。

   

3. 点击 “完成” 后，等待工程创建完成。

   

4. 创建完成。

   

构建工程点击展开

1. 单击工程使工程进入 Active-Debug 模式。

   

2. 点击工具栏上的构建按钮进行工程编译。

   

3. 构建成功后，会显示构建成功的信息。

   

固件下载点击展开

1. 下载 GinoPi 固件镜像

   

2. 下载完成后复位开发板，并通过控制台 UART 查看启动信息

   

核心示例代码

硬件定时器示例相关 API

• rt_device_find：查找硬件定时器设备，返回设备句柄；
• rt_device_open：打开设备；
• rt_device_set_rx_indicate：注册超时回调函数，定时器超时后在中断上下文触发；
• rt_device_control + HWTIMER_CTRL_MODE_SET：设置定时模式（单次 / 周期）；
• rt_device_write：设置超时时间并启动定时器；
• rt_device_control + HWTIMER_CTRL_STOP：停止定时器计数；

• HWTIMER 示例

#define HWTIMER_TEST_TIMEOUT_SEC    1
#define HWTIMER_TEST_DURATION_MS    5000    // 测试运行时长 5 s//

static rt_err_t hwtimer_timeout(rt_device_t dev, rt_size_t size)// 超时回调函数
{
    RT_UNUSED(dev);
    RT_UNUSED(size);
    rt_kprintf("[hwtimer] timeout, tick=%lu\n", (unsigned long)rt_tick_get());
    return RT_EOK;
}

static int hwtimer_example(int argc, char *argv[])// HWTIMER 测试入口函数
{
    rt_device_t dev;
    rt_hwtimer_mode_t mode;
    rt_hwtimerval_t timeout;
    rt_err_t err;

    if (argc != 2)
    {
        hwtimer_usage();
        return -RT_ERROR;
    }

    mode = HWTIMER_MODE_PERIOD;
    timeout.sec = HWTIMER_TEST_TIMEOUT_SEC;
    timeout.usec = 0;

    dev = rt_device_find(argv[1]);// 查找硬件定时器设备
    if (dev == RT_NULL)
    {
        rt_kprintf("Can't find hwtimer device: %s\n", argv[1]);
        return -RT_ERROR;
    }
    err = rt_device_open(dev, RT_DEVICE_OFLAG_RDWR);
    if (err != RT_EOK)
    {
        rt_kprintf("Open %s failed, err=%d\n", argv[1], err);
        return err;
    }
    err = rt_device_set_rx_indicate(dev, hwtimer_timeout);// 注册超时回调

    if (err != RT_EOK)
    {
        rt_device_close(dev);
        rt_kprintf("Set callback for %s failed, err=%d\n", argv[1], err);
        return err;
    }

    err = rt_device_control(dev, HWTIMER_CTRL_MODE_SET, &mode);// 设置定时模式
    if (err != RT_EOK)
    {
        rt_device_close(dev);
        rt_kprintf("Set mode for %s failed, err=%d\n", argv[1], err);
        return err;
    }

    if (rt_device_write(dev, 0, &timeout, sizeof(timeout)) != sizeof(timeout))// 启动定时器
    {
        rt_device_close(dev);
        rt_kprintf("Start %s failed\n", argv[1]);
        return -RT_ERROR;
    }

    rt_kprintf("[hwtimer] %s started: period, %lu.%06lu s\n", argv[1],
                (unsigned long)timeout.sec, (unsigned long)timeout.usec);

    rt_thread_mdelay(HWTIMER_TEST_DURATION_MS);
    rt_device_control(dev, HWTIMER_CTRL_STOP, RT_NULL);// 停止周期定时器
    rt_device_close(dev);
    rt_kprintf("[hwtimer] %s test finished\n", argv[1]);
    return RT_EOK;
}

运行示例

操作步骤

1. 将程序下载到开发板；
2. 打开串口终端连接开发板；
3. 在终端输入 hwtimer_example hwtimer30 命令，以周期模式启动定时，定时周期为 1 s；
4. 定时器每次超时触发回调并打印日志，累计运行 5 s 后自动停止定时器并退出。

预期结果

验证 GD32H77D 开发板的硬件定时器周期定时与超时回调功能：启动后每隔 1 s 输出一次超时日志， 共输出 5 次，随后停止定时并结束测试，命令行为如下：

RT-Thread 终端

msh >hwtimer_example hwtimer30
[hwtimer] hwtimer30 started: period, 1.000000 s
[hwtimer] timeout, tick=10980
[hwtimer] timeout, tick=11980
[hwtimer] timeout, tick=12980
[hwtimer] timeout, tick=13980
[hwtimer] timeout, tick=14980
[hwtimer] hwtimer30 test finished