xt_hal_pin_mux - 引脚复用

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

---

一、概述

xt_hal_pin_mux 是 XTINY HAL 引脚复用配置模块，提供唯一的函数 xt_hal_pin_mux（引脚复用） 用于设置引脚的复用功能。在芯片上，同一物理引脚可用于 GPIO、I2C、SPI、UART 等多种功能，通过引脚复用配置选择当前所需功能。

设计原则 ：

• 极简接口 ：模块仅一个函数，职责单一明确
• SOC 定义驱动 ：复用模式枚举由平台 SOC 头文件定义，本模块只负责执行配置

1.1 依赖

依赖	用途
xt_hal_internal.h	错误码类型 xt_err_t 及平台内部定义

---

二、核心概念

2.1 引脚复用

芯片引脚通常具有多个功能（如 GPIO、UART_TX、I2C_SCL 等），通过配置复用寄存器来选择当前使用哪种功能。使用任何外设前（I2C、SPI、UART 等），必须先将其使用的引脚配置为对应的复用功能。

2.2 IO 编号与 mode

• io ：物理引脚编号，由平台定义合法范围
• mode ：复用功能编号，由 xt_soc.h 中的 enum xt_hal_pin_mux 定义，具体可选值取决于芯片型号

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_pin_mux（引脚复用） 。

函数签名	说明
xt_err_t xt_hal_pin_mux(uint8_t io, uint8_t mode)	设置指定引脚的复用功能

---

四、编译配置

无编译配置项。

---

五、常见模式

5.1 外设初始化前配置引脚

#include "xt_hal_pin_mux.h"
#include "xt_hal_i2c.h"
 
void init_i2c_with_pins(void) {
    /* 1. 先将引脚配置为 I2C 复用功能 */
    xt_hal_pin_mux(10, XT_HAL_PIN_MUX_I2C1_SCL);
    xt_hal_pin_mux(11, XT_HAL_PIN_MUX_I2C1_SDA);
 
    /* 2. 再初始化 I2C 外设 */
    xt_hal_i2cm_setup(0, 400000, 10, 11);
}

5.2 引脚功能切换

#include "xt_hal_pin_mux.h"
 
void switch_pin_to_gpio(uint8_t io) {
    xt_hal_pin_mux(io, XT_HAL_PIN_MUX_GPIO);
}
 
void switch_pin_to_uart_tx(uint8_t io) {
    xt_hal_pin_mux(io, XT_HAL_PIN_MUX_UART1_TX);
}

---

六、已知行为与限制

行为	说明
IO 范围由平台定义	无效的 io 值返回 XT_EINVAL
mode 合法性由平台校验	部分平台不完全校验 mode 值，传非法值可能导致未定义行为
配置立即生效	调用后引脚功能即时切换
无查询接口	不支持读取当前引脚的复用配置