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

一、概述

xt_hal_spilcd 是 xtiny 平台的 LCD SPI 总线驱动模块，提供 LCD 命令/参数传输、RGB 像素数据传输的基本接口。支持阻塞和非阻塞 0 拷贝两种模式，以及采样沿、字节序、时钟频率等配置。

设计理念： SPI 底层传输，不封装 LCD 控制器逻辑 。本模块只负责 LCD SPI 总线的数据收发，不包含 LCD 初始化序列、窗口设置、显存管理等上层逻辑（这些由 LCD 驱动层负责）。

1.1 设计原则

命令-参数模型 ：每次传输都以一个命令字节开头，后跟参数或数据
阻塞 vs 非阻塞 ： _block 函数在传输完成后返回； _0copy 函数立即返回，通过回调通知完成
自动模式推断 ： setup 根据传入引脚自动判断 3 线/4 线模式和单向/双向模式

1.2 依赖

仅依赖 xt_hal_internal.h （ xt_error.h ）。

二、核心概念

2.1 自动模式推断

xt_hal_spilcd_setup 根据引脚参数自动决定 SPI 模式：

条件	模式	dummy 周期
dcx_pin 有效	专用 DCX 引脚（4 线）	8
dcx_pin 无效	DCX 编码在数据中（3 线）	9
sdi_pin 和 sdo_pin 都有效	单向 SPI	—
否则	双向 SPI	—

2.2 传输类型对比

函数	传输内容	阻塞	缓冲区生命周期
tx_param_block	命令 + 参数	是	函数返回后可释放
rx_param_block	命令 + 读取参数	是	函数返回后数据就绪
tx_data_0copy	命令 + 数据	否	传输完成前不可释放
tx_data_0copy_block	命令 + 数据	是	函数返回时可释放

2.3 已废弃接口

以下三个函数已不再支持，保留宏定义仅用于兼容旧代码，调用无效果：

这些模式现在由 setup 根据引脚自动推断。

三、API 参考

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

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_spilcd_setup(uint8_t lcd_id, uint8_t csx_pin, uint8_t scl_pin, uint8_t sdi_pin, uint8_t sdo_pin, uint8_t dcx_pin)	初始化 LCD SPI 接口
xt_err_t xt_hal_spilcd_close(uint8_t lcd_id)	关闭 LCD SPI 接口

3.2 配置

函数签名	说明
xt_err_t xt_hal_spilcd_set_cb(uint8_t lcd_id, xt_hal_spilcd_cb_t cb)	设置回调函数
xt_err_t xt_hal_spilcd_set_sample_edge(uint8_t lcd_id, bool falling)	设置采样时钟沿（true=下降沿）
xt_err_t xt_hal_spilcd_set_rgb565_swap(uint8_t lcd_id, bool enable)	设置 RGB565 字节交换
xt_err_t xt_hal_spilcd_set_freq(uint8_t lcd_id, uint32_t freq_hz)	设置时钟频率（Hz），自动取最近档位

3.3 数据传输

函数签名	说明
int32_t xt_hal_spilcd_tx_param_block(uint8_t lcd_id, uint8_t cmd, const uint8_t *param, uint32_t len)	阻塞发送命令 + 参数
int32_t xt_hal_spilcd_rx_param_block(uint8_t lcd_id, uint8_t cmd, uint8_t *param, uint32_t len)	阻塞发送命令 + 读取参数
int32_t xt_hal_spilcd_tx_data_0copy(uint8_t lcd_id, uint8_t cmd, const uint8_t *data, uint32_t len)	非阻塞 0 拷贝发送命令 + 数据
int32_t xt_hal_spilcd_tx_data_0copy_block(uint8_t lcd_id, uint8_t cmd, const uint8_t *data, uint32_t len)	阻塞 0 拷贝发送命令 + 数据

3.4 类型

类型签名	说明
typedef void (*xt_hal_spilcd_cb_t)(uint8_t lcd_id, uint32_t event_id)	LCD 回调函数类型
enum xt_hal_spilcd_event_id	事件类型： XT_HAL_SPILCD_EVENT_DONE 、 XT_HAL_SPILCD_EVENT_ERROR

3.5 配置常量

常量	说明
XT_HAL_SPILCD_SPI_UNIDIR	单向 SPI 模式
XT_HAL_SPILCD_SPI_BIDIR	双向 SPI 模式
XT_HAL_SPILCD_DCX_ENCODED	DCX 编码在数据中（3 线）
XT_HAL_SPILCD_DCX_DEDICATED	专用 DCX 引脚（4 线）
XT_HAL_SPILCD_SAMPLE_RISE	上升沿采样
XT_HAL_SPILCD_SAMPLE_FALL	下降沿采样
XT_HAL_SPILCD_DUMMY_CYCLE(n)	虚拟周期宏
XT_HAL_SPILCD_RGB565_NORMAL	RGB565 正常字节序
XT_HAL_SPILCD_RGB565_SWAP	RGB565 交换字节序

四、常见模式

4.1 基本 LCD 写命令流程

#include "xt_hal_spilcd.h"
 
uint8_t lcd_id = 0;
 
xt_hal_spilcd_setup(lcd_id, 0, 1, 2, 3, 4);
 
uint8_t init_seq[] = {0x11, 0x00};
xt_hal_spilcd_tx_param_block(lcd_id, 0x11, init_seq, 2);
 
xt_hal_spilcd_close(lcd_id);

五、已知行为与限制

setup 的自动模式推断基于引脚是否有效，有效引脚为 != XT_HAL_GPIO_INVALID_ID
set_freq 的频率档位取决于平台，超出范围自动取边界，参数值为建议值，实际取最近档位
tx_data_0copy 的 data 缓冲区在传输完成前不可释放，需等回调通知 XT_HAL_SPILCD_EVENT_DONE
tx_data_0copy_block 虽然阻塞，但也会调用回调（在传输完成前），与 tx_data_0copy 的回调语义一致
三个已废弃宏（ set_spi_bidir / set_dcx_mode / set_dummy_cycles ）调用无任何效果，新代码不应使用