显示与存储

文档版本：V1.0 | 适用系统：RT-Thread | 适用硬件：C-3576BQ V10 核心板 + M4-R2（ShimetaPi）底板 | 更新日期：2026-10-23

1. 概述

本文档涵盖 M4-R2（RK3576）平台在 RT-Thread 下的显示驱动与 SPI Flash 存储方案，分为两大部分：

部分	内容	RK3576 支持状态
显示	RT-Thread Display 驱动框架	参考说明（官方文档支持芯片列表未含 RK3576）
存储	SPI Flash（Nor / Nand）驱动与 XIP	参考说明（基于 Rockchip 通用 SPI Flash 方案）

硬件事实（已验证）：M4-R2 核心板具备 HDMI（最高 4Kx2K@120Hz）、MIPI DSI（4 Lanes，最高 2560×1600）和 eDP（与 HDMI 二选一）显示接口（S-02 / S-04）。RT-Thread 侧显示驱动的具体支持状态以实际发布的 RK3576 RT-Thread 版本为准（待板上确认）。

---

2. 硬件准备

2.1 核心板

项目	规格
型号	C-3576BQ V10（RK3576）
SoC	Rockchip RK3576（4×A72 + 4×A53）
内存	4GB LPDDR5

2.2 底板

项目	规格
型号	M4-R2（ShimetaPi）
SPI Flash	板载 SPI Nor / SPI Nand（具体型号与是否引出以实际底板物料和原理图为准）
显示接口	HDMI（4Kx2K@120Hz）、MIPI DSI（4 Lanes）、eDP（与 HDMI 二选一）

2.3 SPI Flash 接口说明

RK3576 提供三种 SPI 相关控制器（Rockchip 通用 IP，具体以实际 RK3576 SDK 为准，待板上确认）：

控制器	全称	特点
FSPI	Flexible SPI	支持 XIP、Dual/Quad/Octal 模式
SFC	Serial Flash Controller	专用串行 Flash 控制器
SPI	标准 SPI	通用 SPI 控制器

注意：FSPI 是 XIP 功能的首选控制器，SFC 为专用控制器，SPI 为通用控制器。三种控制器在 RK3576 上的使能情况以实际 SDK 为准。

---

3. 软件准备

3.1 RT-Thread 环境

• RT-Thread 内核（含 DFS 设备文件系统）
• RT-Thread Studio 或 ENV 工具链

3.2 关键驱动文件

文件	用途	状态
drv_snor.c	SPI Nor Flash 驱动	参考说明
drv_display.c	显示驱动（官方支持列表未含 RK3576）	参考说明
drv_vop.c	VOP 显示控制器驱动（RK3576 显示控制器名称以实际 SDK 为准）	参考说明
drv_dsi.c	DSI 接口驱动	参考说明
drv_panel.c	Panel 驱动	参考说明

3.3 HAL 层文件

文件	用途	状态
hal_fspi.c	FSPI 控制器 HAL	参考说明
hal_spi.c	SPI 控制器 HAL	参考说明
hal_snor.c	SPI Nor 通用 HAL	参考说明
hal_spinand.c	SPI Nand HAL	参考说明

---

4. 操作步骤

4.1 SPI Nor Flash 配置

在 menuconfig 中启用 SPI Nor 支持：

RT-Thread Components →
  Device →
    [*] Using MTD NOR flash device driver    # RT_USING_MTD_NOR=y
    [*] Using SPI NOR flash on SPI bus       # RT_USING_SNOR=y
        SPI NOR flash speed (80000000) →     # RT_SNOR_SPEED（实际值以 SDK 为准）
        [ ] Use FSPI Host                    # FSPI_HOST（按实际选择）
        [ ] Use SFC Host                     # SFC_HOST
        [ ] Use SPI Host                     # SPI_HOST

4.2 SPI Nand Flash 配置

RT-Thread Components →
  Device →
    [*] Using MTD NAND flash device driver   # RT_USING_MTD_NAND=y
    [*] Using SPI NAND flash on SPI bus      # RT_USING_SPINAND=y
        SPI NAND flash speed (80000000) →    # RT_SPINAND_SPEED（实际值以 SDK 为准）
        [*] Using FTL layer                  # RT_USING_FTIL=y

4.3 文件系统配置

RT-Thread Components →
  Virtual File System →
    [*] Using device virtual file system     # RT_USING_DFS=y
    [*] Using working directory              # RT_USING_DFS_USING_WORKDIR=y
    DFS file system types →
      [*] Using elm-chan fatfs               # elm FatFs
          DFS_ELM_FAT_SECTOR_SIZE (4096) →  # Nor: 4096, Nand: 2048

4.4 分区表配置

SPI Flash 的分区表存储在 Flash 前 2KB 位置，由 drv_snor.c 中的 snor_partition_init() 初始化（参考说明）。

标准分区布局：

分区	说明
snor_boot	Bootloader 区域
snor_system	系统固件
snor_app	应用程序
snor_data	用户数据

分区表格式遵循 RK_PARTITION 规范，位于 Flash 首 2KB。具体分区名称与布局以实际 RT-Thread BSP 配置为准（待板上验证）。

---

5. 代码详解

5.1 SPI Nor MTD API

SPI Nor Flash 通过 MTD（Memory Technology Device）接口操作：

#include <rtdevice.h>

/* 擦除块 —— 最小单位需按 Flash 规格对齐 */
rt_err_t rt_mtd_nor_erase_block(struct rt_mtd_nor_device *device,
                                rt_uint32_t offset, rt_uint32_t len);

/* 写入 —— 最小单位 1 字节 */
rt_err_t rt_mtd_nor_write(struct rt_mtd_nor_device *device,
                          rt_off_t offset, const rt_uint8_t *data, rt_size_t len);

/* 读取 —— 最小单位 1 字节 */
rt_err_t rt_mtd_nor_read(struct rt_mtd_nor_device *device,
                         rt_off_t offset, rt_uint8_t *data, rt_size_t len);

关键约束：擦除操作必须按块对齐（Nor Flash 通用为 4096 字节，以实际 Flash 规格为准）。

5.2 XIP（eXecute In Place）机制

XIP 允许 CPU 通过映射内存地址直接访问 Flash，无需将代码拷贝到 RAM。

启用条件：使用 FSPI 控制器时自动启用（Rockchip 通用方案，RK3576 具体以实际 SDK 为准）。

XIP 挂起/恢复流程：

当 Flash 进行擦除或写入操作时，必须先挂起 XIP：

/* XIP 挂起 —— 3 步 */
rt_err_t snor_xip_suspend(struct rt_mtd_nor_device *device)
{
    /* 步骤 1: 禁用 XIP 映射 */
    /* 步骤 2: 等待当前 XIP 事务完成 */
    /* 步骤 3: 释放 Flash 总线给擦除/写入操作 */
    return RT_EOK;
}

/* XIP 恢复 —— 3 步 */
rt_err_t snor_xip_resume(struct rt_mtd_nor_device *device)
{
    /* 步骤 1: 等待 Flash 操作完成 */
    /* 步骤 2: 重新使能 XIP 映射 */
    /* 步骤 3: 恢复 Flash 总线访问 */
    return RT_EOK;
}

上述代码为流程示意（参考说明），具体实现以实际 RT-Thread BSP 源码为准。

多主机 XIP 冲突处理：当 Flash 处于 XIP 模式时，其他主机（如 DMA）发起的擦除/写入操作必须先挂起 XIP，操作完成后恢复。

5.3 文件系统架构

SPI Flash 的软件栈层次：

应用程序
    ↓
DFS（Device File System）
    ↓
FS Layer（elm FatFs）
    ↓
DHARA FTL（Nand）/ Mini FTL（Nor）
    ↓
MTD（Memory Technology Device）
    ↓
RTT SPI Nor / RTT SPI Nand 驱动
    ↓
HAL（hal_fspi.c / hal_spi.c / hal_snor.c / hal_spinand.c）
    ↓
硬件 SPI 控制器（FSPI / SFC / SPI）

5.4 文件系统创建

使用以下命令创建文件系统镜像（参考说明，命令以实际 BSP 提供工具为准）：

# 创建根文件系统镜像
./mkroot.sh

# 创建 FAT 文件系统（Nor Flash，扇区大小 4096）
mkfs.fat -F 32 -s 8 -S 4096 /dev/snor

# 创建 FAT 文件系统（Nand Flash，扇区大小 2048）
mkfs.fat -F 32 -s 8 -S 2048 /dev/spinand

5.5 DFS 挂载表配置

#include <dfs_fs.h>

static struct dfs_mount_table mount_table[] =
{
    { "snor", "/", "elm", 0, 0 },
    { "spinand", "/data", "elm", 0, 0 },
    { 0, 0, 0, 0, 0 },
};

5.6 显示驱动架构说明

RT-Thread Display 驱动框架采用 CRTC → VOP → Plane → Encoder → Connector → Panel 的分层架构（Rockchip 通用显示框架，RK3576 具体显示控制器实现以实际 SDK 为准）。

参考说明：RK3576 未显式列入 Display 指南（V1.4.0）的支持芯片列表，显示驱动开发建议优先参考 Rockchip 后续发布的 RK3576 RT-Thread 适配，或等待上游文档更新。

---

6. 常见问题

6.1 显示相关

问题	原因	解决方案
显示驱动无法编译	RK3576 不在 Display 文档支持列表中	等待上游/官方更新 RK3576 支持
HDMI 无输出	显示驱动尚未适配 RK3576	以实际 RT-Thread BSP 为准

6.2 SPI Flash 存储相关

问题	原因	解决方案
SPI Flash 未识别	控制器选择错误	检查 menuconfig 中 FSPI_HOST / SFC_HOST / SPI_HOST 配置
读写速度异常	时钟频率配置错误	确认 RT_SNOR_SPEED 或 RT_SPINAND_SPEED 设置
文件系统挂载失败	扇区大小不匹配	Nor 使用 4096，Nand 使用 2048
XIP 模式下擦除失败	未挂起 XIP	调用 snor_xip_suspend() 后再执行擦除
Nand 读写错误	FTL 未启用	确认 RT_USING_FTIL=y
分区表丢失	Flash 被全片擦除	重新写入 RK_PARTITION 分区表（前 2KB）

---

7. 相关文档

文档	说明
RT-Thread环境与工程入口	AMP 架构、SDK 目录、构建流程入口
BSP与启动	调试串口配置、menuconfig、finsh shell
I2C-SPI-USB	RT-Thread 外设驱动（I2C、SPI、USB）
显示DRM驱动	Linux 侧 DRM 显示驱动（对照参考）
HDMI显示驱动	Linux 侧 HDMI 显示驱动（对照参考）
核心板参数	硬件事实基线（显示接口、eMMC）
40PIN引脚定义	底板接口清单（显示/存储相关接口）