eMMC¶

1. 简介¶

1.1 定义¶

单eMMC：eMMC仅作为存储设备，不从该eMMC启动。
eMMC启动：系统从eMMC启动（适用于仅外挂eMMC或在PSRAM上启动的方案）。

2. 单eMMC使用教程¶

2.1 适用范围¶

芯片系列：58系列、52A系列（内置NORFlash）、56系列（外挂NOR/nandFlash，通过SD2接口连接eMMC）。
硬件板子：mod566（sdio-tf接口，SD2，驱动IP为drv_sdio）、mod587（SD1接口，驱动IP为drv_sdhci）、EVB567、EVB587。

示例：以下教程以mod566为例（硬件使用sd1接口，驱动IP为sdhci）。

2.2 pinmux配置¶

确认eMMC接口与芯片手册中的SD接口对应。
SD接口pinmux配置参考：

上电配置：在对应芯片平台的bsp_power.c文件中添加上电函数：

上电调用：在芯片平台的bsp_init.c中调用；若当前 board 未拆分该文件，则在对应的 BSP 初始化入口中调用：

2.3 menuconfig配置¶

eMMC 的 SDIO 总开关路径为：menuconfig (Top) → SiFli SDK configuration → Board Config → SDIO (BSP_USING_SDIO)。BSP_USING_SDIO 直接依赖 BF0_HCPU，且其父级板级驱动菜单不在 PC Simulator 工程显示，因此仅在非 PC Simulator 的 HCPU 工程显示；启用后自动选择 RT_USING_SDIO。打开后，根据硬件连接选择 SDMMC1 或 SDMMC2；对应的 SDIO mode 分别设置为 1 --> EMMC。SDHCI 平台在选择 SDMMC 控制器后会自动选择所需的 SDHCI 驱动。

2.3.1 打开`BSP_USING_SDIO`以启用sdio接口¶

2.3.2 选择sdio驱动IP（与芯片平台和SD接口相关）¶

平台	SD1接口	SD2接口
56x	sdhci	sdio
52x	sdio	NA
58x	sdhci	sdhci

配置示例：

2.3.3 设置eMMC频率¶

2.3.4 配置线宽模式（默认4线，选中为8线模式）¶

2.3.5 使能DDR模式（默认SDR，选中为DDR模式（52M））¶

2.3.6 打开文件系统¶

若使用 FAT 文件系统，路径为：menuconfig (Top) → SiFli SDK configuration → RTOS → RT Thread → RT-Thread Components → Device virtual file system → Using device virtual file system (RT_USING_DFS) → Enable elm-chan fatfs (RT_USING_DFS_ELMFAT)。先打开 RT_USING_DFS，才会显示 RT_USING_DFS_ELMFAT。更多说明参见 FAT 文件系统。

2.4 excel表配置¶

code及root分区放在内部/外挂NOR Flash，eMMC仅作为外部存储。
配置eMMC大小及blk对齐：

更多配置参考《Flash分区应用笔记》。

2.5 启动log¶

eMMC初始化log：

文件系统挂载log（首次mount会自动格式化）：

2.6 异常排查¶

2.6.1 初始化失败¶

检查eMMC供电是否正常，reset引脚是否为高电平。
用“LightWork.exe”验证pinmux与芯片引脚功能表一致（以566的PA27-SD1_CMD为例）：

确认时钟使能：若“SDEMMC1”为0，需调用HAL_RCC_EnableModule(RCC_MOD_SDMMC1);开启时钟：

确认时钟源配置：

读写超时：检查访问buff地址（不可在ITCM区域（0x00000000），需在SRAM/PSRAM且4字节对齐）。

2.6.2 mount失败¶

文件系统个数不足：在 menuconfig (Top) → SiFli SDK configuration → RTOS → RT Thread → RT-Thread Components → Device virtual file system → Using device virtual file system (RT_USING_DFS) 中调整 The maximal number of mounted file system (DFS_FILESYSTEMS_MAX)；该项只有在启用 RT_USING_DFS 后显示。
无LBR分区信息：首次加载时格式化。
读写超时：可能因供电不稳、高频走线问题等，可降低频率尝试。

3. eMMC启动教程¶

适用范围

场景：芯片仅外挂eMMC，或code放eMMC并在PSRAM启动。
芯片：52x、56x、58x（以566外挂eMMC为例）。

3.1 配置步骤¶

3.1.1 pinmux配置¶

与“单eMMC使用教程”一致。

3.1.2 menuconfig配置¶

除单eMMC配置外，需额外设置：
1. 关闭“OTA_EXT_V3”（仅适用于 NOR Flash 方案升级）：

打开“OTA_56X_NAND”（临时解决编译报错）：

3.1.3 excel表配置¶

关闭其他外部Flash选项，仅开启SD0；双PSRAM需打开PSRAM1和PSRAM2：

配置code启动地址及分区信息：

更多配置参考《Flash分区应用笔记》。

3.1.4 启动log¶

文件系统加载log：

3.2 异常排查¶

启动无log（可能因eMMC搬移到PSRAM异常）：
1. 用“SIFLI Butterfli”工具对比eMMC内code与原始code：

确认eMMC搬移到PSRAM的地址正确（566需为PSRAM1，XIP地址对应PSRAM1地址）。
其他初始化异常与“单eMMC”排查方法一致。

4. eMMC低功耗模式¶

eMMC低功耗分两种模式：
1. 掉电模式（SDIO_POWER_PM_ALL_DOWN）
2. 不掉电模式（SDIO_POWER_PM_UP）
供电说明：eMMC由VCC（器件电源）和VCCQ（颗粒电源）供电，功耗对应Icc与Iccq（参考规格书）。

4.1 基础配置¶

先在 menuconfig (Top) → SiFli SDK configuration → SiFli Built-in Components → Power Management (Low Power Configuration) (BSP_USING_PM) 启用低功耗管理；该项会自动选择 RT_USING_PM。随后在 menuconfig (Top) → SiFli SDK configuration → RTOS → RT Thread → RT-Thread Components → Using Power Management device drivers (RT_USING_PM) → Select PM Mode 选择 Enable Standby Mode (PM_STANDBY_ENABLE)。SDIO_PM_MODE 依赖 PM_STANDBY_ENABLE，未启用 Standby 时不会显示。

SDIO 低功耗开关的完整路径为：menuconfig (Top) → SiFli SDK configuration → Board Config → SDIO (BSP_USING_SDIO) → Common Option → Enable SDIO PM (SDIO_PM_MODE)。先启用 BSP_USING_SDIO；该项直接依赖 BF0_HCPU，且其父级板级驱动菜单不在 PC Simulator 工程显示，并自动选择 RT_USING_SDIO。SDIO_PM_MODE 直接依赖 PM_STANDBY_ENABLE，默认关闭；启用后才显示 Select SDIO PM Mode，其默认选项为 VCC and VCCQ Don't lose power (SDIO_POWER_PM_UP)。

（注：目前支持 Standby 模式）

4.2 掉电模式（SDIO_POWER_PM_ALL_DOWN）¶

在上述 Enable SDIO PM (SDIO_PM_MODE) 下的 Select SDIO PM Mode 中选择 VCC and VCCQ All power off (SDIO_POWER_PM_ALL_DOWN)：

特点：睡眠唤醒后需重新初始化eMMC，耗时约50ms~60ms。

4.3 不掉电模式（SDIO_POWER_PM_UP）¶

在 menuconfig (Top) → SiFli SDK configuration → Board Config → SDIO (BSP_USING_SDIO) → Common Option → Enable SDIO PM (SDIO_PM_MODE) → Select SDIO PM Mode 中选择 VCC and VCCQ Don't lose power (SDIO_POWER_PM_UP)：

特点：睡眠唤醒仅恢复HCPU端eMMC寄存器。

5. FAQ¶

驱动文件问题：联系FAE人员对齐驱动文件。
eMMC裸读写方式：初始化完成后调用接口（引用#include "mmcsd_core.h"），addr基地址为0xa0000000：

buff地址错误：报错如图时，检查buff地址是否4字节对齐且非0x00000000开头：

finsh测试指令：

带文件系统：

fs_read /1.txt 1024  /* 读 / 1.txt，大小 1024K */
fs_write /1.txt 1024 /* 写 / 1.txt，大小 1024K */

裸读写：

fs_read_code 10 85 1024  /* 读地址 0xa0000000+10，buff 初始数据 85，大小 1024 字节 */
fs_write_code 10 85 1024 /* 写地址 0xa0000000+10，数据 85，大小 1024 字节 */

其他注意事项：
- 55X不支持DDR模式。
- eMMC读写速率低：参考eMMC读写性能文件。
- 睡眠唤醒方案：参考硬件设计手册。