LISA QSPILCD DMA 传输示例

功能说明

演示使用 QSPI LCD 驱动进行 DMA（直接内存访问）模式的数据传输，适用于大数据量像素传输场景。

底层使用 GPDMA 硬件进行数据搬移，CPU 无需参与，通过信号量实现异步等待。

新特性

DMA 硬件传输：无需 CPU 参与数据搬移，降低 CPU 占用
异步非阻塞：调用后立即返回，DMA 后台传输
高带宽传输：支持四线并行传输，适合大数据量场景
信号量同步：传输完成后通过信号量通知应用层

硬件连接

PA18: QSPI CLK（时钟）
PA19: QSPI CS（片选，可选使用 GPIO 控制）
PA20: QSPI IO0（数据线 0）
PA21: QSPI IO1（数据线 1）
PA22: QSPI IO2（数据线 2）
PA23: QSPI IO3（数据线 3）

连接到支持 QSPI 接口的 LCD 显示屏模组。

使用场景

适用于需要高速传输 LCD 显示数据的场景，底层采用 DMA 硬件传输，CPU 占用更低，支持四线并行传输提升带宽。

示例步骤

获取 QSPI LCD 设备
配置 CS 引脚（可选，使用 GPIO 手动控制）
准备传输数据缓冲区（32 字节对齐）
配置传输参数（数据线模式、位宽、DMA 使能）
调用 lisa_qspilcd_transfer() 启动 DMA 传输
调用 lisa_qspilcd_wait_done() 等待传输完成

编译

重要提示：在编译前，请先确认您使用的开发板型号。SDK 目前支持以下开发板：

arcs_evb - ARCS EVB 评估板
arcs_mini - ARCS Mini 开发板

根据您的开发板型号，选择对应的编译命令：

在示例目录下执行编译:

# 使用 arcs_evb 开发板
./build.sh -C -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -DBOARD=arcs_mini

Note

如果在 SDK 根目录执行，需要指定示例路径:

# 使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_mini

Note

确保已安装对应的工具链。

烧录

编译完成后，使用 SDK tools 目录下的 cskburn 工具烧录固件:

./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Note

烧录参数说明：

-s /dev/ttyUSB0：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - 不同开发板或 USB 转串口芯片可能使用不同的设备名
-b 3000000：烧录波特率（3Mbps）
0x0：烧录起始地址
build/arcs.bin：编译生成的固件路径
-C arcs：芯片类型

注意事项：

确保开发板已正确连接到电脑
如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

终端输出：

=== LISA QSPILCD DMA example ===
QSPILCD device ready
CS GPIO configured
DMA transfer started (Quad lane, 8-bit)
DMA transfer complete, time: 2 ms
All transfers completed successfully!

核心 API

API	说明
`lisa_device_get()`	获取 QSPI LCD 设备
`lisa_qspilcd_control()`	配置 QSPI 控制参数（模式、时钟极性、数据位宽、总线速度等）
`lisa_qspilcd_cs_configure()`	配置 CS 引脚（GPIO 手动控制）
`lisa_qspilcd_cs_control()`	控制 CS 引脚电平
`lisa_qspilcd_transfer()`	启动数据传输（DMA 模式）
`lisa_qspilcd_wait_done()`	等待 DMA 传输完成

控制参数配置

使用 lisa_qspilcd_control() 配置 QSPI LCD 的工作参数：

uint32_t control = LISA_QSPILCD_TXIO_DMA |      /* TX 使用 DMA 模式 */
                   LISA_QSPILCD_CPOL0_CPHA0 |   /* 时钟极性和相位 */
                   LISA_QSPILCD_MSB_LSB |       /* MSB 优先 */
                   LISA_QSPILCD_MODE_MASTER |   /* 主机模式 */
                   LISA_QSPILCD_DATA_BITS(8);   /* 8 位数据宽度 */

lisa_qspilcd_control(qspi, control, 50*1000*1000);  /* 50MHz 总线速度 */

控制码字段说明

字段	宏定义	说明
TX I/O 模式	`LISA_QSPILCD_TXIO_PIO`	使用 CPU 轮询发送
	`LISA_QSPILCD_TXIO_DMA`	使用 DMA 发送
	`LISA_QSPILCD_TXIO_AUTO`	自动选择（PIO 或 DMA）
时钟极性/相位	`LISA_QSPILCD_CPOL0_CPHA0`	CPOL=0, CPHA=0（Mode 0）
	`LISA_QSPILCD_CPOL0_CPHA1`	CPOL=0, CPHA=1（Mode 1）
	`LISA_QSPILCD_CPOL1_CPHA0`	CPOL=1, CPHA=0（Mode 2）
	`LISA_QSPILCD_CPOL1_CPHA1`	CPOL=1, CPHA=1（Mode 3）
位序	`LISA_QSPILCD_MSB_LSB`	高位优先（MSB first）
	`LISA_QSPILCD_LSB_MSB`	低位优先（LSB first）
主从模式	`LISA_QSPILCD_MODE_MASTER`	主机模式
	`LISA_QSPILCD_MODE_SLAVE`	从机模式
数据位宽	`LISA_QSPILCD_DATA_BITS(n)`	设置数据位宽（n = 1~32）

函数原型

lisa_err_t lisa_qspilcd_control(lisa_device_t *dev, uint32_t control, uint32_t arg);

dev: QSPI LCD 设备句柄
control: 控制码，由上述宏按位或组合
arg: 附加参数，通常为总线速度（Hz）
返回值: 成功返回 LISA_DEVICE_OK，失败返回错误码

DMA 传输说明

lisa_qspilcd_transfer() 在 DMA 模式下的工作原理：

底层实现：GPDMA 硬件自动搬移数据到 QSPI FIFO，CPU 无需参与
返回时机：调用后立即返回，不等待传输完成
完成通知：DMA 传输完成后触发中断，释放信号量
等待方式：调用 lisa_qspilcd_wait_done() 阻塞等待完成
返回值：成功返回 0，超时返回 LISA_DEVICE_ERR_TIMEOUT

关键代码

/* 获取 QSPI LCD 设备 */
lisa_device_t *qspi = lisa_device_get("qspilcd0");

/* 配置 CS 引脚（使用 GPIO 手动控制） */
lisa_device_t *gpio = lisa_device_get("gpioa");
lisa_qspilcd_cs_configure(qspi, gpio, 19);

/* 准备传输数据（32 字节对齐） */
static uint8_t tx_buf[256] __attribute__((aligned(32)));

/* 配置 DMA 传输参数 */
lisa_qspilcd_xfer_t xfer = {
    .buf = tx_buf,
    .size_bytes = sizeof(tx_buf),
    .lane = LISA_QSPILCD_LANE_QUAD,  /* 四线模式 */
    .data_bits = 8,
    .use_dma = true,                  /* DMA 模式 */
};

/* 拉低 CS，启动传输 */
lisa_qspilcd_cs_control(qspi, false);
lisa_qspilcd_transfer(qspi, &xfer);

/* 等待 DMA 完成 */
lisa_qspilcd_wait_done(qspi, 1000);

/* 拉高 CS，结束传输 */
lisa_qspilcd_cs_control(qspi, true);

配置说明

DMA 通道配置

在 prj.conf 中配置 DMA 通道：

CONFIG_LISA_QSPILCD_GPDMA_CH=0

内存对齐要求

要求：DMA 模式下发送缓冲区必须 32 字节对齐
实现：使用 __attribute__((aligned(32))) 属性
原因：DMA 控制器对内存地址有对齐要求，可提升传输效率

数据线模式

模式	枚举值	说明
单线	`LISA_QSPILCD_LANE_SINGLE`	使用 IO0 传输，兼容性最好
双线	`LISA_QSPILCD_LANE_DUAL`	使用 IO0/IO1 传输，带宽翻倍
四线	`LISA_QSPILCD_LANE_QUAD`	使用 IO0-IO3 传输，带宽最高

注意事项

DMA 通道冲突：确保配置的 DMA 通道没有与其他外设冲突
缓冲区生命周期：DMA 传输完成前不能释放或修改发送缓冲区内容
内存对齐：DMA 模式必须使用 32 字节对齐的发送缓冲区
传输同步：DMA 模式必须调用 lisa_qspilcd_wait_done() 等待完成
CS 控制时序：手动 CS 模式下，需在传输前拉低、传输后拉高 CS