版本：0.1 | 日期：2026-07-03 | 路径： components/xt_board/

一、概述

xt_board 是 xt-sdk 的板级配置层，通过 编译时宏分发 机制选择对应板级头文件。每个板级头文件以宏定义形式声明该板卡上所有外设的引脚号、复用功能和外设编号，驱动代码通过这些宏间接引用硬件资源，实现板卡无关的驱动开发。

1.1 设计原则

**编译时分发**： xt_board.h 是纯预处理器分发器，零运行时开销
**纯宏定义**：板级配置全部为 #define 宏，不产生任何 RAM/Flash 占用
**引脚+复用成对**：每个外设引脚同时定义物理引脚号（ _PIN ）和复用功能（ _MUX ）
**模拟器板兜底**：所有引脚设为 XT_HAL_GPIO_INVALID_ID ，支持主机端编译验证

1.2 支持的板卡

板卡	宏开关	头文件	@defgroup	说明
E837N V01	XT_SDK_BOARD_E837N_V01	xt_board_e837n_v01.h	xt_board_e837n_v01（E837N 板）	全功能板（I2C、音频 I2S、ADC、LCD、SPI、UART、PWM、PM）
E68 V01	XT_SDK_BOARD_E68_V01	xt_board_e68_v01.h	xt_board_e68_v01（E68 板）	精简板（仅音频 I2S + 电源使能）
模拟器	XT_SDK_BOARD_SIMULATOR	xt_board_simulator.h	xt_board_simulator（模拟器板）	所有引脚无效，仅用于编译验证

1.3 依赖

依赖	用途
xt_hal（HAL 驱动总入口）	XT_HAL_I2C_* 、 XT_HAL_GPIO_INVALID_ID 等 HAL 层常量
xt_io	XT_IO_PD_* 、 XT_IO_AON_* 等引脚定义与复用宏
xt_adc	XT_ADC_CH_* ADC 通道定义

二、核心概念

2.1 编译时分发机制

xt_board.h 仅 23 行，核心逻辑是 #if defined() 链：

#if defined(XT_SDK_BOARD_E837N_V01)
#   include "xt_board_e837n_v01.h"
#elif defined(XT_SDK_BOARD_E68_V01)
#   include "xt_board_e68_v01.h"
#elif defined(XT_SDK_BOARD_SIMULATOR)
#   include "xt_board_simulator.h"
#else
#   error "未识别的板型，请检查 XT_SDK_BOARD 环境变量"
#endif

板型选择通过 xmake 构建系统的 XT_SDK_BOARD 配置项传入，在编译期确定。若未指定任何板型宏，预处理阶段直接 #error 终止，避免生成错误固件。

2.2 引脚与复用成对约定

每个外设引脚由两个宏共同定义：

后缀	含义	示例
_PIN	物理引脚号	XT_BRD_UART_TX_PIN → XT_IO_PD_7
_MUX	引脚复用功能	XT_BRD_UART_TX_MUX → XT_IO_PD_7_MUX_UART2_TX

驱动代码在初始化时同时使用两者：先用 _PIN 配置 GPIO，再用 _MUX 设置复用功能。这种成对设计确保引脚和复用功能不会因为修改其中一个而忘记修改另一个。

2.3 模拟器板的设计意图

xt_board_simulator.h 将所有引脚设为 XT_HAL_GPIO_INVALID_ID 、所有编号设为 0 。其作用是：

让驱动代码在 无真实硬件 的环境下通过编译
驱动初始化时检查到 XT_HAL_GPIO_INVALID_ID 可跳过硬件操作
配合 Unity 测试框架在主机上运行单元测试

2.4 板卡间的外设覆盖差异

不同板卡定义的外设宏集合不同。E837N 是全功能板，定义了 I2C、音频、ADC、GPIO、LCD（ST7735/ST7789）、PM、PWM、SPI、UART 全部外设。E68 仅定义了音频 I2S 和电源使能相关引脚。

驱动代码引用某板卡 未定义 的板级宏时，会在预处理阶段报错。这意味着添加新板卡时，必须为该板卡上使用的所有外设提供完整宏定义，否则相关驱动无法编译。

三、API 参考

板级宏定义的完整列表请查看 xt_board（板级配置）及其子组 xt_board_e837n_v01（E837N 板）、 xt_board_e68_v01（E68 板）、 xt_board_simulator（模拟器板）。

四、常见模式

4.1 驱动中使用板级宏

// UART 驱动初始化
void board_uart_init(void) {
    // 使用板级宏，而非硬编码引脚
    xt_hal_gpio_init(XT_BRD_UART_TX_PIN, XT_GPIO_MODE_AF);
    xt_hal_gpio_set_mux(XT_BRD_UART_TX_PIN, XT_BRD_UART_TX_MUX);
    xt_hal_gpio_init(XT_BRD_UART_RX_PIN, XT_GPIO_MODE_AF);
    xt_hal_gpio_set_mux(XT_BRD_UART_RX_PIN, XT_BRD_UART_RX_MUX);
 
    xt_hal_uart_init(XT_BRD_UART);
}

4.2 LCD 驱动引脚配置

void board_lcd_st7789_init(void) {
    // 背光
    xt_hal_gpio_init(XT_BRD_LCD_ST7789_BACKLIGHT_PIN, XT_GPIO_MODE_OUTPUT);
    xt_hal_gpio_write(XT_BRD_LCD_ST7789_BACKLIGHT_PIN, 1);
 
    // 复位
    xt_hal_gpio_init(XT_BRD_LCD_ST7789_RESET_PIN, XT_GPIO_MODE_OUTPUT);
    xt_hal_gpio_write(XT_BRD_LCD_ST7789_RESET_PIN, 0);
    xt_hal_delay_ms(10);
    xt_hal_gpio_write(XT_BRD_LCD_ST7789_RESET_PIN, 1);
 
    // SPI 引脚复用
    xt_hal_gpio_set_mux(XT_BRD_LCD_ST7789_SCL_PIN, XT_BRD_LCD_ST7789_SCL_MUX);
    xt_hal_gpio_set_mux(XT_BRD_LCD_ST7789_SDI_PIN, XT_BRD_LCD_ST7789_SDI_MUX);
    xt_hal_gpio_set_mux(XT_BRD_LCD_ST7789_CSX_PIN, XT_BRD_LCD_ST7789_CSX_MUX);
}

4.3 添加新板卡

创建 xt_board_<name>.h ，为所有需要的外设定义 XT_BRD_* 宏
在 xt_board.h 的分发链中添加 #elif defined(XT_SDK_BOARD_<NAME>) 分支
在 xmake 构建系统中添加对应的 XT_SDK_BOARD 配置项

五、反模式

反模式	问题	正确做法
驱动中硬编码引脚号	更换板卡需修改驱动代码	始终使用 XT_BRD_* 宏
只定义 _PIN 忘记 _MUX	复用功能未配置，引脚不工作	引脚和复用成对定义、成对使用
模拟器板中设置真实引脚	主机编译可能引用不存在的硬件常量	模拟器板所有引脚设为 XT_HAL_GPIO_INVALID_ID
新板卡只定义部分外设宏	未定义的宏导致引用它的驱动编译失败	为该板卡上使用的所有外设提供完整宏定义
未在 xt_board.h 中注册新板卡	#error 终止编译	添加 #elif 分支并定义对应宏开关