版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

一、概述

xt_hal_gpio 是 XTINY HAL 层的 GPIO 驱动模块，提供引脚输入/输出配置、电平读写、中断/唤醒回调等能力。所有平台都必须实现此模块。

1.1 设计原则

位掩码模式配置 ：所有模式（输入/输出、上下拉、开漏、中断边沿/电平、唤醒）通过一个 uint32_t 位掩码参数一次性配置，减少函数调用
中断上下文安全 ：中断回调在临界区保护的环境下调用，内部使用链表管理注册的 GPIO
复用保护 ：同一 IO 重复 setup 返回 XT_EBUSY ，防止误配置

1.2 依赖

依赖	用途
xt_hal_internal.h	HAL 内部类型与工具宏

二、核心概念

2.1 模式位掩码

setup 的 mode 参数是以下标志的按位或组合：

标志	位	说明
XT_HAL_GPIO_INPUT	B0	输入模式
XT_HAL_GPIO_OUTPUT	B0	输出模式
XT_HAL_GPIO_PULLUP	B1	上拉
XT_HAL_GPIO_PULLDOWN	B2	下拉
XT_HAL_GPIO_OD	B3	开漏输出（仅输出模式）
XT_HAL_GPIO_RISING_EDGE	B4	上升沿中断（仅输入模式）
XT_HAL_GPIO_FALLING_EDGE	B5	下降沿中断（仅输入模式）
XT_HAL_GPIO_WAKEUP	B6	唤醒使能（仅输入模式）
XT_HAL_GPIO_HIGH_LEVEL	B7	高电平中断（仅输入模式）
XT_HAL_GPIO_LOW_LEVEL	B8	低电平中断（仅输入模式）

常用组合： XT_HAL_GPIO_BOTH_EDGE （双边沿）、 XT_HAL_GPIO_BOTH_LEVEL （双电平）。

2.2 中断与唤醒事件

回调函数接收两个参数： io （引脚编号）和 event_id （事件类型）：

事件	值	说明
XT_HAL_GPIO_EVENT_INT	0	普通 GPIO 中断
XT_HAL_GPIO_EVENT_WAKEUP	1	IO 唤醒事件

2.3 close 行为

close 会取消中断/唤醒注册、释放中断节点内存，并恢复引脚为默认输入状态（无上下拉）。如果引脚未注册中断，则仅重置引脚配置。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_gpio（GPIO 驱动）。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_gpio_setup(uint8_t io, uint32_t mode, xt_hal_gpio_cb_t cb)	初始化 GPIO，配置模式和回调
xt_err_t xt_hal_gpio_close(uint8_t io)	关闭 GPIO，释放资源并恢复默认状态

3.2 电平操作

函数签名	说明
void xt_hal_gpio_set_level(uint8_t io, uint8_t level)	设置输出电平（0 低，1 高）
uint8_t xt_hal_gpio_get_level(uint8_t io)	获取当前电平（0 低，1 高）

3.3 类型

类型签名	说明
xt_hal_gpio_cb_t	回调函数类型： void (*)(uint8_t io, uint32_t event_id)
enum xt_hal_gpio_event_id	事件 ID 枚举（ XT_HAL_GPIO_EVENT_INT / XT_HAL_GPIO_EVENT_WAKEUP ）

四、常见模式

4.1 输出模式——控制 LED

#include "xt_hal_gpio.h"
 
void led_init(void) {
    xt_hal_gpio_setup(5, XT_HAL_GPIO_OUTPUT, NULL);
}
 
void led_on(void)  { xt_hal_gpio_set_level(5, 1); }
void led_off(void) { xt_hal_gpio_set_level(5, 0); }

4.2 输入模式——上升沿中断

#include "xt_hal_gpio.h"
 
static void button_cb(uint8_t io, uint32_t event_id) {
    if (event_id == XT_HAL_GPIO_EVENT_INT) {
        /* 按键按下 */
    }
}
 
void button_init(void) {
    xt_hal_gpio_setup(6,
        XT_HAL_GPIO_INPUT | XT_HAL_GPIO_PULLUP | XT_HAL_GPIO_RISING_EDGE,
        button_cb);
}

4.3 输入模式——电平读取

#include "xt_hal_gpio.h"
 
void sensor_init(void) {
    xt_hal_gpio_setup(7, XT_HAL_GPIO_INPUT | XT_HAL_GPIO_PULLDOWN, NULL);
}
 
uint8_t sensor_read(void) {
    return xt_hal_gpio_get_level(7);
}

五、已知行为与限制

行为	说明
同一 IO 不可重复 setup	重复注册返回 XT_EBUSY
中断模式不支持输出	同时设置 OUTPUT 和中断标志返回 XT_EINVAL
中断模式必须传 cb	cb 为 NULL 返回 XT_EINVAL
close 恢复默认状态	GPIO 被重置为输入、无上下拉
set_level / get_level 对无效 IO 安全	无效 IO 静默返回（无操作或返回 0）