通用步骤

[English]

本文档总结了 ESP-IDF 中 SD 存储卡的通用实现流程，涵盖其基础说明、初始化步骤以及相关执行流程。

通过掌握本文档内容，开发者能够快速理解有关 SD 存储卡的关键逻辑，为后续示例学习提供统一参考。

SD 存储卡概述

SD（Secure Digital）存储卡是一种广泛使用的非易失性存储介质，常用于嵌入式系统、数码相机、手机等设备，用于存储数据、文件和程序。它体积小、功耗低、容量可扩展。

在嵌入式系统中，SD 存储卡模块主要用途包括：

数据存储：保存传感器采集的数据、日志信息或用户文件。
程序扩展：存储应用程序资源，如图片、音频、配置文件。
文件系统支持：通过 FAT 文件系统访问数据，方便与 PC 或其他设备交换数据。
固件升级：通过存储卡存放固件镜像，实现 OTA 或手动升级。

SD 存储卡关键技术要点

在使用 SD 存储卡模块时，需要掌握一些核心知识点，以确保卡的正确初始化、稳定读写以及高效使用。本节将对接口模式、总线配置、文件系统、初始化流程、错误处理等关键要点进行说明。

接口模式

SD 存储卡通过两种接口与主控芯片通信：SPI 模式和 SD 模式（也称 SDMMC 模式）。

SPI 模式 使用标准 SPI 总线进行数据交换，通信协议简单、兼容性好，因此几乎所有 MCU 都可以支持，适合低速数据存取或资源受限的应用场景。然而 SPI 模式的传输速度有限，无法满足大容量数据的高速读写需求。

SD/SDMMC 模式 利用 ESP32 内置的 SD/MMC 控制器直接访问存储卡，可以使用一条或四条数据线并行传输数据，从而实现高速访问。

接口模式决定了数据传输速度、硬件连接方式和初始化参数

总线宽度

总线宽度决定数据传输的并行程度和速度。SD 卡在 SD 模式下可以选择在一线或四线模式下工作。

一线模式：使用单条数据线（DAT0）进行数据传输，硬件布线简单、节省引脚资源，但数据传输速度较低，适合低速或简单应用。
四线模式：使用四条数据线（DAT0–DAT3）并行传输数据，速度约为单线模式的四倍，但引脚占用更多，对硬件布局要求更高。

选择适当的总线模式需要权衡性能和引脚资源，同时在初始化时设置正确的线数参数，否则可能导致读写失败或性能低下。在 ESP32 中，如果使用 SDMMC 模式，一般推荐四线模式以获得较高性能；如果资源有限或使用 SPI 模式，则通常采用一线模式。

文件系统

SD 卡上的数据通常通过 FAT 文件系统进行管理。FAT 文件系统提供目录和文件管理能力，使得数据存取可以像在普通计算机上一样方便。在 ESP-IDF 中，FAT 文件系统通过 FATFS 接口进行访问，支持文件的创建、读取、写入和删除等操作。

理解文件系统的结构和机制非常重要，因为文件系统挂载失败、非正常断电或未同步数据都可能导致数据损坏。因此在设计应用时，需要确保在读写操作后及时同步文件，或者在异常情况下提供格式化或恢复策略。文件系统的可靠性直接关系到 SD 卡模块在应用中的稳定性。

卡初始化

在任何读写操作之前，SD 卡必须经过完整的初始化过程：

检测 SD 卡是否存在：判断卡是否已插入，并识别卡类型（SD、SDHC、SDXC 或 MMC）。
配置总线参数：如接口模式（SPI/SDMMC）、时钟频率、线数（1-bit/4-bit）。
挂载文件系统：将 FAT 文件系统挂载到指定路径，供应用程序访问。

如果初始化失败，可能是由于卡未插入、接线错误、总线参数配置不当或者文件系统损坏，因此建议在应用中设计合理的错误处理和重试机制。

数据一致性与错误处理

在实际应用中，SD 卡可能出现多种异常情况，例如

读写失败：由于硬件抖动、卡老化或通信异常。
卡拔出：在访问过程中被拔出，会导致挂载失效。
文件系统损坏：非正常断电或未同步数据可能破坏文件结构。

为保证数据一致性，必须在软件层面实现错误检测与处理机制，常见做法包括检查读写返回值、在重要数据写入后进行同步（flush）、以及在异常情况下重新挂载或格式化卡。

对于数据关键型应用，例如日志存储、传感器数据采集等，错误处理策略尤为重要，它直接影响系统稳定性和数据可靠性。

性能优化

SD 卡的性能不仅受接口模式和总线线数影响，还与时钟频率、缓存策略和任务访问方式密切相关。

时钟频率：SDMMC 模式支持高频访问，在该模式下合理提高时钟频率可以提升数据传输速度。
缓存和缓冲区：使用读写缓存可以减少文件系统操作次数，从而降低延迟、提升性能。
多任务访问：在多任务环境，例如 FreeRTOS 中，多任务同时访问 SD 卡需要使用互斥锁或同步机制，避免数据冲突和资源争用。

性能优化不仅能提高读写速度，也可以保证系统在高负载下的稳定性。

速度模式配置

在使用 SD 卡时，需要根据卡片支持的总线和速率模式进行配置，以保证数据传输的可靠性和性能。UHS-I（Ultra High Speed Phase I）是 SD 卡的一种高速总线规范，相比普通 SD 模式可以提供更高的传输速率。UHS-I 下常见的速率模式包括 SDR50（Single Data Rate 50 MHz）和 DDR50（Double Data Rate 50 MHz）。

SDR50 模式 为单数据率模式，数据在时钟上升沿传输一次，理论最大传输速率约为 50 MB/s。 DDR50 模式 为双数据率模式，数据在时钟上升沿和下降沿均传输一次，理论最大速率可达 100 MB/s。

检测 SD 卡所支持的速率模式对于控制器配置至关重要。在不同速率模式下，SD 卡需要对应的控制器配置才能保证稳定通信：

时钟配置：SDR50 和 DDR50 的时钟频率和数据传输方式不同，控制器必须根据模式调整时钟和信号采样。
数据完整性：高速模式对电压、上拉/下拉电阻和 PCB 布线要求更严格。错误配置可能导致读写失败。
性能优化：如果检测到 SD 卡支持高速模式，可以启用相应模式以提升数据传输性能，否则退回到标准速率保证可靠性。

..note:

不同芯片对 SD 卡速度模式的支持可能有所差异，可通过 `ESP 芯片&模组选型工具 <https://products.espressif.com/#/product-selector?language=zh&names=>` 确认支持的模式，并据此进行控制器配置。

SD 存储卡通用步骤

在使用 SD 存储卡时，初始化和挂载是必不可少的步骤。ESP-IDF 中提供了多种底层 API 来完成主机控制器初始化、卡片识别、文件系统挂载和虚拟文件系统注册等操作。为了简化流程，ESP-IDF 提供了一个一站式（All-in-One）便利函数 esp_vfs_fat_sdmmc_mount()，它将底层驱动初始化与文件系统挂载步骤整合在一起，开发者只需调用该函数即可完成 SD 卡初始化和文件系统挂载，无需逐一调用多个底层 API。

该函数在初始化流程中承担了整合控制的角色，具体包括以下几个方面：

初始化主机控制器：配置 SDMMC 或 SDSPI 主机，建立 ESP 芯片与 SD 卡硬件之间的通信。
探测并初始化 SD 卡：自动识别卡片类型（如 SD、SDHC、SDXC），完成容量、传输速率等参数的读取与配置。
挂载 FAT 文件系统：调用 FATFS 库挂载文件系统，使 SD 卡能够作为存储介质被访问。
注册 VFS（虚拟文件系统）：将 FATFS 文件系统注册到 ESP-IDF 的 VFS 层，应用程序可以直接使用标准 C 文件操作函数来访问 SD 卡上的文件。

在调用该函数时，需要传入若干配置参数，用于控制挂载点、主机与插槽配置方式以及挂载行为。参数说明如下，参考自 FAT 文件系统：

传入参数	参数描述	参数解释
`base_path`	挂载点路径	指定 SD 卡挂载到 VFS 的路径前缀。
`host_config`	主机控制器配置	定义 SDMMC 或 SDSPI 主机的初始化参数，通常通过 `SDMMC_HOST_DEFAULT()` 或 `SDSPI_HOST_DEFAULT()` 宏生成。
`slot_config`	插槽配置	指定 SD 卡槽的配置，包括引脚映射和总线宽度，通常通过 `SDMMC_SLOT_CONFIG_DEFAULT()` 或 `SDSPI_SLOT_CONFIG_DEFAULT()` 宏生成。
`mount_config`	挂载配置	控制文件系统挂载方式的结构体。
`out_card`	卡信息结构体指针	输出参数，返回指向已初始化的 `sdmmc_card_t` 结构体的指针，其中包含卡片容量、CID/CSD 信息等，用于后续操作。

通过这一函数，SD 卡初始化流程被大幅简化，仅需根据需求配置各个传参即可完成卡片初始化与文件系统挂载，开发效率与代码可读性均得到提升。

挂载点路径

挂载点路径用于指定 SD 卡在虚拟文件系统（VFS）中的访问位置。所有文件操作都将以该路径作为前缀。常用路径为 "/sdcard"，挂载后文件可以通过类似 "/sdcard/filename.txt" 的路径访问。设计挂载点时需要确保路径唯一，避免与系统或其他挂载点冲突，从而保证文件系统操作的正确性。

主机控制器配置

主机控制器通过结构体 sdmmc_host_t 配置，用于定义 ESP 芯片与 SD 卡硬件之间通信的参数，包括时钟频率、DMA 设置以及工作模式。具体结构体成员说明如下：

结构体成员	成员描述	成员配置
`flags`	主机支持的协议和总线宽度标志位	根据应用需求设置，至少设置支持的总线宽度，常用标志见下表。
`slot`	对应的插槽编号	根据实际进行选择，通常为 0 或 1。
`max_freq_khz`	主机支持的最大频率	初始可用默认值（20000 kHz）；如果需要高速模式，可设置为 40000 kHz。
`io_voltage`	控制器 I/O 电压	常用 3.3 V，设置为 0.0 时表示使用默认值。
`init`	初始化主机驱动	必须提供函数实现。
`set_bus_width`	设置总线宽度	函数指针，用于根据配置设置总线宽度。
`do_transaction`	执行 SD/MMC 命令	指定核心操作函数。
`set_card_clk`	设置卡片时钟	在高速模式或特定频率时使用。
`command_timeout_ms`	单条命令超时时间	根据需求设置，或使用默认值。

常用标志
常用标志	标志说明
`SDMMC_HOST_FLAG_1BIT`	支持 1 线 SD/MMC。
`SDMMC_HOST_FLAG_4BIT`	支持 4 线 SD/MMC。
`SDMMC_HOST_FLAG_8BIT`	支持 8 线 MMC（SD 卡不支持 8 线）。
`SDMMC_HOST_FLAG_SPI`	支持 SPI 协议。
`SDMMC_HOST_FLAG_DDR`	支持 DDR 模式。
`SDMMC_HOST_FLAG_DEINIT_ARG`	表示 `deinit` 函数带 `slot` 参数。
`SDMMC_HOST_FLAG_ALLOC_ALIGNED_BUF`	表示内部分配符合 DMA 对齐要求的缓冲区（512B）。

对于 SDMMC 模式，可以通过 SDMMC_HOST_DEFAULT() 宏生成默认配置；对于 SDSPI 模式，可以使用 SDSPI_HOST_DEFAULT() 宏生成配置。选择主机类型时应结合硬件接口实际情况，不同模式在速率和功能支持上有所差异。

正确配置主机控制器能够确保数据传输的稳定性与性能。

插槽配置

插槽通过结构体 sdmmc_slot_config_t 配置，用于定义 SD 卡插槽的具体参数，包括 GPIO 引脚映射和总线宽度（一线或四线模式）。具体结构体成员说明如下，参考自 SDMMC 主机驱动：

结构体成员	成员描述	成员配置
`clk`	CLK 信号引脚	用于 SD/MMC 时钟，确保 GPIO 与硬件实际连线匹配。
`cmd`	CMD 信号引脚	用于 SD 卡命令传输，确保 GPIO 与硬件实际连线匹配。
`D0 - D7`	数据线引脚	根据数据宽度选择需要的引脚数量，其中 `D0` 是最低位，`D7` 是最高位。确保 GPIO 与硬件实际连线匹配。
`gpio_cd` / `cd`	卡片检测引脚，可通过两种名字访问	如果使用 SD 卡插拔检测功能，需要指定实际连接的 GPIO；若不使用可设置为 `GPIO_NUM_NC` 表示未连接。
`gpio_wp` / `wp`	写保护信号，可通过两种名字访问	如果使用写保护功能，需要指定实际连接的 GPIO，并设置写保护极性标志；若不使用可设置为 `GPIO_NUM_NC` 表示未连接。
`width`	总线宽度	确认硬件支持的总线宽度，常用为一线或四线。
`flags`	控制 SD 卡槽功能的标志位	根据应用需求设置，常用标志见下表。

常用标志
常用标志	标志说明	标志解释
`SDMMC_SLOT_FLAG_INTERNAL_PULLUP`	启用内部上拉（仅调试/示例用途）	建议仍通过外部上拉电阻保证信号可靠性。
`SDMMC_SLOT_FLAG_WP_ACTIVE_HIGH`	写保护极性	置 1 表示高电平有效，置 0 表示低电平有效。
`SDMMC_SLOT_FLAG_UHS1`	UHS-I 模式	置 1 表示开启 UHS-I 模式，可提高高速传输速率。

对于 SDMMC 模式，可以使用 SDMMC_SLOT_CONFIG_DEFAULT() 宏生成默认配置；对于 SDSPI 模式，需要根据实际接线修改 GPIO 引脚，例如 MISO、MOSI、CLK 和 CS。

插槽配置直接影响数据传输效率和接口兼容性，因此应根据硬件设计进行调整。

挂载配置

文件挂载通过结构体 esp_vfs_fat_sdmmc_mount_config_t 配置，文件系统挂载的行为和限制，是保证文件系统正常使用的重要参数。具体结构体成员说明如下，参考自 FAT 文件系统：

结构体成员	成员描述	成员配置
`format_if_mount_failed`	挂载失败时是否格式化	当设置为 `true` 时，如果文件系统挂载失败，函数会先对 SD 卡进行格式化，然后重新尝试挂载；设置为 `false` 时，在挂载失败时直接返回错误。
`max_files`	最大文件数	限制同时打开的文件数量，典型值为 5 至 10，防止文件句柄耗尽。
`allocation_unit_size`	分配单元大小	FAT 文件系统的分配单元大小影响存储效率和性能，常用设置为 16 KB 或 32 KB。
`disk_status_check_enable`	分区标签	用于指定挂载的分区，通常设置为 `NULL` 表示使用默认分区。
`out_card`	卡信息结构体指针	输出参数，返回指向已初始化的 `sdmmc_card_t` 结构体的指针，其中包含卡片容量、CID/CSD 信息等，用于后续操作。

合理配置挂载参数可以平衡存储效率与数据安全性，例如在需要保留已有数据的场景下应关闭自动格式化选项。

卡信息结构体指针

该参数用于返回指向已初始化 SD 卡信息的指针，结构体类型为 sdmmc_card_t。通过该结构体可以获取卡片容量、CID、CSD、总线速度和类型等详细信息，便于后续操作和调试。在使用时，需要先定义指针变量并传入函数：

..code:

sdmmc_card_t *card;