概述

本文介绍如何在 睿擎工业开发平台 中创建并运行 SPI 总线通信 示例工程，基于 RT-Thread 设备驱动框架， 以 W25QXX 系列 NorFlash 为例，演示 SPI 从设备挂载、总线参数配置以及读取厂商 ID 与器件容量 ID 的标准流程， 帮助读者掌握 SPI 总线的通信时序与外设控制方法。

W25Q NorFlash 简介

W25Q 系列是采用 SPI 总线接口的串行 NorFlash 存储器，支持标准 / 双线 / 四线 SPI 通信， 具备页编程、扇区与块擦除等操作能力，并内建写保护与状态寄存器锁定机制。 该器件采用非易失性存储技术，掉电后数据可长期保存，适用于固件存储、参数区与数据缓存等需要大容量、高读写速度的应用场景。

硬件连接

开发板的 SPI 总线与 W25QXX 芯片已完成硬件连接，芯片位置如图所示：

查看排针原理图与引脚对应图（对照接线）

完整排针引脚表见 硬件连接 — HAT 扩展排针引脚对应关系。

查询配置树获取 SPI 资源

根据 GD32H77D 配置树可知：

• GD32H77D 片内集成多路 SPI 控制器，本示例使用 spi3，用户可在配置树文件中按实际硬件选择其他实例；
• 示例中的片选信号由 PA7 引脚提供，用户可按实际硬件连接修改片选引脚参数。

读取 W25Q NorFlash 设备的数据

本示例通过 SPI 总线读取 W25QXX 的 JEDEC ID（厂商 ID、内存类型编码与容量编码）， 用于确认器件在线并识别存储容量，是验证 SPI 通信链路与 NorFlash 器件状态的常用手段。

构建与烧录

创建工程点击展开

1. 依次点击 “文件” -> “新建” -> "RT-Thread RuiChing App 项目"。

   

2. 在弹出新建向导中选择 开发版 、BSP: 、示例 、 调试器/下载器。选择好之后点击 “完成”。

   

3. 点击 “完成” 后，等待工程创建完成。

   

4. 创建完成。

   

构建工程点击展开

1. 单击工程使工程进入 Active-Debug 模式。

   

2. 点击工具栏上的构建按钮进行工程编译。

   

3. 构建成功后，会显示构建成功的信息。

   

固件下载点击展开

1. 下载 GinoPi 固件镜像

   

2. 下载完成后复位开发板，并通过控制台 UART 查看启动信息

   

核心示例代码

SPI 示例相关 API

• rt_spi_bus_attach_device：将 SPI 从设备挂载到指定总线，需要提供设备名称、总线名称与片选引脚；
• rt_spi_configure：配置 SPI 从设备的通信参数，包括时钟极性与相位、数据位宽以及最大通信速率。

• SPI W25QXX 示例

int spi_w25qxx_example(int argc, char **argv)
{
    struct rt_spi_device *spi;
    struct rt_spi_configuration config =
    {
        .mode = RT_SPI_MODE_0 | RT_SPI_MSB,
        .data_width = 8,
        .max_hz = 10000000,
    };
    w25qxx_device_t w25qxx;
    const struct w25qxx_info *info;
    char spi_name[RT_NAME_MAX];

    if (argc != 4)
    {
        w25qxx_usage(argv[0]);
        return -RT_EINVAL;
    }

    if (argv[1][0] == '\0' || argv[2][0] == '\0' || argv[3][0] == '\0')
    {
        w25qxx_usage(argv[0]);
        return -RT_EINVAL;
    }

    rt_snprintf(spi_name, sizeof(spi_name), "%s_spi", argv[1]);
    spi = (struct rt_spi_device *)rt_device_find(spi_name);
    if (spi == RT_NULL)
    {
        spi = (struct rt_spi_device *)rt_malloc(sizeof(*spi));
        if (spi == RT_NULL || rt_spi_bus_attach_device(spi, spi_name, argv[2],// 挂载 SPI 从设备
                                     (void *)argv[3]) != RT_EOK)
        {
            if (spi != RT_NULL) rt_free(spi);
            rt_kprintf("attach SPI device '%s' to '%s' failed\n", spi_name, argv[2]);
            return -RT_ERROR;
        }
    }

    if (spi == RT_NULL || rt_spi_configure(spi, &config) != RT_EOK)// 配置 SPI 从设备参数
    {
        rt_kprintf("configure SPI device '%s' failed\n", spi_name);
        return -RT_ERROR;
    }

    w25qxx = w25qxx_create(argv[1], spi_name);
    if (w25qxx == RT_NULL)
    {
        rt_kprintf("create W25QXX device '%s' failed\n", argv[1]);
        return -RT_ERROR;
    }

    info = w25qxx_get_info(w25qxx);
    if (info == RT_NULL)
    {
        rt_kprintf("read W25QXX information failed\n");
        w25qxx_delete(w25qxx);
        return -RT_ERROR;
    }

    rt_kprintf("[%s] JEDEC ID: %02X %02X %02X, size: %u KB\n",
               argv[1], info->manufacturer_id, info->memory_type,
               info->capacity_id, info->total_size / 1024);

    w25qxx_delete(w25qxx);
    return RT_EOK;
}

运行示例

操作步骤

1. 将程序下载到开发板；
2. 打开串口终端连接开发板；
3. 在终端输入 spi_w25qxx_example 22 spi3 PA7 命令，参数依次为设备名称 22（可自定义）、 SPI 总线 spi3、片选引脚 PA7。

预期结果

终端打印 JEDEC ID 与存储容量信息：厂商 ID 0xEF 表示 Winbond，容量编码 0x18 对应 16 MB 容量， 说明 SPI 通信链路与 NorFlash 器件工作正常：

RT-Thread 终端

msh >spi_w25qxx_example 22 spi3 PA7
[D/w25qxx] JEDEC id: MFR:0xEF Type:0x40 Cap:0x18
[I/w25qxx] [22] init ok: spi=22_spi size=16384KB sector=4096B page=256B
[22] JEDEC ID: EF 40 18, size: 16384 KB