版本：0.1 | 日期：2025-07-03 | 路径： components/xt_sys_event/

一、概述

xt_sys_event 定义了 xt-sdk 全局系统事件 ID 枚举，并提供 HAL 中断到事件系统的桥接封装。它解决两个问题：一是为发布订阅式事件总线（ xt_event（事件管理））提供统一的、无冲突的事件编号；二是将裸 HAL 中断回调转化为事件模型，使中断处理逻辑解耦到任务上下文执行。

1.1 设计原则

**集中编号**：所有系统事件 ID 在单一枚举 xt_event_id 中定义，避免跨模块冲突
**域预留**：通过 XT_EVENT_DOMAIN 宏为每个功能域预留连续 ID 段，域内可自由扩展
**用户扩展点**： XT_EVENT_USER_START 之后留给应用层自定义事件
**中断到事件桥接**： hal_event/ 子目录将硬件中断封装为事件发布，回调在任务上下文执行

1.2 依赖

依赖	用途
xt_utils.h	基础类型与工具宏
xt_task （ xt_event.h ）	事件发布订阅机制（ xt_event_publish / xt_event_subscribe ）
xt_hal（HAL 驱动总入口）	硬件抽象层（GPIO、UART 等外设驱动）

二、核心概念

2.1 事件域机制

XT_EVENT_DOMAIN 宏在枚举中声明一个事件域，自动生成 START 和 END 边界值：

#define XT_EVENT_DOMAIN(_name, _num) \
    _XT_ ## _name ## _EVENT_ID_START, \
    _XT_ ## _name ## _EVENT_ID_END = _XT_ ## _name ## _EVENT_ID_START + ((_num) - 1)

例如 XT_EVENT_DOMAIN(WIFI, 16) 会生成 _XT_WIFI_EVENT_ID_START 到 _XT_WIFI_EVENT_ID_END 共 16 个 ID 槽位。域内实际事件在 XT_EVENT_SET_SATRT 和 XT_EVENT_SET_END 之间声明。

2.2 事件 ID 布局

当前 xt_event_id 枚举的 ID 分配：

区段	事件 ID	说明
保留域	XT_EVENT_START (0) ~ 保留域 END	系统保留，4 个槽位
HAL 事件	XT_GPIO_INT	GPIO 中断
	XT_TIMER_TIMEOUT	定时器超时
	XT_UART_RX	UART 接收到数据
	XT_UART_TX_DONE	UART 发送完成
	XT_SPI_XFER_DONE	SPI 传输完成
用户扩展	XT_EVENT_USER_START	应用自定义事件起始

枚举中预留了 ble event 、 cellular event 、 wifi event 、 components event 等注释占位，待后续功能域填充。

2.3 HAL 事件桥接

hal_event/ 子目录实现了"中断 → 事件 → 回调"三段式桥接：

硬件中断 → HAL 驱动回调 → xt_event_publish(事件ID, 参数) → 事件总线分发 → 用户回调（任务上下文）

模块	源文件	触发事件	回调签名	数据编码
GPIO	xt_gpio.c	XT_GPIO_INT	void cb(uint8_t io, uint8_t level)	param = io \\| (level << 16)
UART	xt_uart.c	XT_UART_RX	void cb(uint8_t uart_id, uint32_t event_id)	param = uart_id

GPIO 模块在 HAL 中断回调中读取电平值，将 io 和 level 打包为 uintptr_t 发布到事件总线；UART 模块过滤非 RX 事件后发布。用户回调通过 xt_gpio_setup / xt_uart_setup 注册，在事件分发时被调用。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_sys_event（系统事件 ID）及 hal_event/ 子模块。

3.1 事件域宏

宏签名	说明
XT_EVENT_NUM_DEFAULT	默认事件域槽位数（4）
XT_EVENT_DOMAIN(_name, _num)	在枚举中声明一个事件域，生成 START/END 边界
XT_EVENT_SET_SATRT(_name)	在已存在的事件域中开始声明实际事件
XT_EVENT_SET_END(_name)	结束事件声明，计算实际使用的事件个数

3.2 事件 ID 枚举

枚举值	说明
XT_EVENT_START	事件 ID 起始（0）
XT_GPIO_INT	GPIO 中断
XT_TIMER_TIMEOUT	定时器超时
XT_UART_RX	UART 接收到数据
XT_UART_TX_DONE	UART 发送完成
XT_SPI_XFER_DONE	SPI 传输完成
XT_EVENT_USER_START	用户自定义事件起始

3.3 HAL 事件桥接（hal_event/）

函数签名	说明
void xt_gpio_init(void)	初始化 GPIO 事件模块
void xt_gpio_setup(uint8_t io, uint8_t mode, xt_gpio_cb_t cb)	配置 GPIO 事件监听并注册回调
void xt_uart_init(void)	初始化 UART 事件模块
void xt_uart_setup(uint8_t uart_id, xt_uart_cb_t cb)	配置 UART 事件监听并注册回调

四、编译配置

宏	默认值	说明
XT_EVENT_NUM_DEFAULT	4	默认事件域槽位数
XT_GPIO_INT_NUM	10	GPIO 中断监听最大数量
XT_UART_INT_NUM	2	UART 事件监听最大数量

五、常见模式

5.1 使用 GPIO 事件监听

#include "xt_gpio.h"
 
static void on_gpio_int(uint8_t io, uint8_t level)
{
    printf("GPIO %d triggered, level=%d\n", io, level);
}
 
void app_init(void)
{
    xt_gpio_init();                          /* 初始化 GPIO 事件模块 */
    xt_gpio_setup(5, GPIO_MODE_INPUT_PULLUP, /* 配置 IO5 */
                  on_gpio_int);              /* 注册回调 */
}

5.2 使用 UART 事件监听

#include "xt_uart.h"
 
static void on_uart_rx(uint8_t uart_id, uint32_t event_id)
{
    if (event_id == XT_UART_RX) {
        /* 读取 UART 数据 */
    }
}
 
void app_init(void)
{
    xt_uart_init();              /* 初始化 UART 事件模块 */
    xt_uart_setup(0, on_uart_rx); /* 监听 UART0 */
}

5.3 直接订阅系统事件

跳过 HAL 封装，直接使用 xt_event（事件管理）订阅底层事件 ID：

#include "xt_sys_event.h"
#include "xt_event.h"
 
static void on_spi_done(void *param, void *user_data)
{
    /* SPI 传输完成处理 */
}
 
void app_init(void)
{
    xt_event_subscribe(XT_SPI_XFER_DONE, on_spi_done, NULL);
}

六、反模式

反模式	问题	正确做法
在 HAL 回调中执行耗时操作	中断上下文阻塞	仅 publish 事件，处理逻辑放回调中
超过 XT_GPIO_INT_NUM 注册 GPIO	静态数组溢出，新注册被丢弃	增大宏值或复用监听槽位
回调中直接操作硬件寄存器	可能与驱动状态竞争	通过事件将操作转发到任务上下文
自定义事件 ID 与系统枚举冲突	事件路由错误	自定义事件从 XT_EVENT_USER_START 开始

七、扩展 HAL 事件

添加新的 HAL 事件封装（以 SPI 为例）：

在 xt_sys_event.h 的 xt_event_id 枚举中已有 XT_SPI_XFER_DONE
在 hal_event/ 下创建 xt_spi.h 和 xt_spi.c
xt_spi_init 中调用 xt_event_subscribe(XT_SPI_XFER_DONE, ...) 注册分发回调
xt_spi_setup 中调用 HAL 层注册中断回调，回调中调用 xt_event_publish(XT_SPI_XFER_DONE, ...)
xmake.lua 已通过 add_files("./hal_event/*.c") 自动纳入新源文件