Merge pull request #563 from espressif/feat/new_sd_api

feat(bsp): New SD card API

Author: espzav

bsp/esp-box-3/CMakeLists.txt

@@ -2,6 +2,6 @@ idf_component_register(
     SRCS "esp-box-3.c" "esp-box-3_idf5.c"
     INCLUDE_DIRS "include"
     PRIV_INCLUDE_DIRS "priv_include"
-    REQUIRES driver spiffs
-    PRIV_REQUIRES fatfs esp_lcd
+    REQUIRES driver spiffs fatfs
+    PRIV_REQUIRES esp_lcd
 )

bsp/esp-box-3/esp-box-3.c

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include <string.h>
 #include "driver/gpio.h"
 #include "driver/ledc.h"
 #include "driver/spi_master.h"
@@ -60,7 +61,8 @@ static esp_lcd_panel_handle_t panel_handle = NULL;
 #endif // (BSP_CONFIG_NO_GRAPHIC_LIB == 0)
 
 static esp_lcd_touch_handle_t tp;   // LCD touch handle
-sdmmc_card_t *bsp_sdcard = NULL;    // Global SD card handler
+static sdmmc_card_t *bsp_sdcard = NULL;    // Global uSD card handler
+static bool spi_sd_initialized = false;
 
 /**
  * @brief I2C handle for BSP usage
@@ -185,8 +187,78 @@ esp_err_t bsp_spiffs_unmount(void)
     return esp_vfs_spiffs_unregister(CONFIG_BSP_SPIFFS_PARTITION_LABEL);
 }
 
-esp_err_t bsp_sdcard_mount(void)
+sdmmc_card_t *bsp_sdcard_get_handle(void)
+{
+    return bsp_sdcard;
+}
+
+void bsp_sdcard_get_sdmmc_host(const int slot, sdmmc_host_t *config)
+{
+    assert(config);
+
+    sdmmc_host_t host_config = SDMMC_HOST_DEFAULT();
+
+    memcpy(config, &host_config, sizeof(sdmmc_host_t));
+}
+
+void bsp_sdcard_get_sdspi_host(const int slot, sdmmc_host_t *config)
+{
+    assert(config);
+
+    sdmmc_host_t host_config = SDSPI_HOST_DEFAULT();
+    host_config.slot = slot;
+
+    memcpy(config, &host_config, sizeof(sdmmc_host_t));
+}
+
+void bsp_sdcard_sdmmc_get_slot(const int slot, sdmmc_slot_config_t *config)
+{
+    assert(config);
+    memset(config, 0, sizeof(sdmmc_slot_config_t));
+
+    /* SD card is connected to Slot 0 pins. Slot 0 uses IO MUX, so not specifying the pins here */
+    config->cd = SDMMC_SLOT_NO_CD;
+    config->wp = SDMMC_SLOT_NO_WP;
+    config->cmd = BSP_SD_CMD;
+    config->clk = BSP_SD_CLK;
+    config->d0 = BSP_SD_D0;
+    config->d1 = BSP_SD_D1;
+    config->d2 = BSP_SD_D2;
+    config->d3 = BSP_SD_D3;
+    config->width = 4;
+    config->flags = 0;
+}
+
+void bsp_sdcard_sdspi_get_slot(const spi_host_device_t spi_host, sdspi_device_config_t *config)
+{
+    assert(config);
+    memset(config, 0, sizeof(sdspi_device_config_t));
+
+    config->gpio_cs   = BSP_SD_SPI_CS;
+    config->gpio_cd   = SDSPI_SLOT_NO_CD;
+    config->gpio_wp   = SDSPI_SLOT_NO_WP;
+    config->gpio_int  = GPIO_NUM_NC;
+    config->host_id = spi_host;
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 2, 0)
+    config->gpio_wp_polarity = SDSPI_IO_ACTIVE_LOW;
+#endif
+}
+
+esp_err_t bsp_sdcard_sdmmc_mount(bsp_sdcard_cfg_t *cfg)
 {
+    sdmmc_host_t sdhost = {0};
+    sdmmc_slot_config_t sdslot = {0};
+    const esp_vfs_fat_sdmmc_mount_config_t mount_config = {
+#ifdef CONFIG_BSP_SD_FORMAT_ON_MOUNT_FAIL
+        .format_if_mount_failed = true,
+#else
+        .format_if_mount_failed = false,
+#endif
+        .max_files = 5,
+        .allocation_unit_size = 16 * 1024
+    };
+    assert(cfg);
+
     gpio_config_t power_gpio_config = {
         .mode = GPIO_MODE_OUTPUT,
         .pin_bit_mask = 1ULL << BSP_SD_POWER
@@ -196,6 +268,31 @@ esp_err_t bsp_sdcard_mount(void)
     /* SD card power on first */
     ESP_ERROR_CHECK(gpio_set_level(BSP_SD_POWER, 0));
 
+    if (!cfg->mount) {
+        cfg->mount = &mount_config;
+    }
+
+    if (!cfg->host) {
+        bsp_sdcard_get_sdmmc_host(SDMMC_HOST_SLOT_0, &sdhost);
+        cfg->host = &sdhost;
+    }
+
+    if (!cfg->slot.sdmmc) {
+        bsp_sdcard_sdmmc_get_slot(SDMMC_HOST_SLOT_0, &sdslot);
+        cfg->slot.sdmmc = &sdslot;
+    }
+
+#if !CONFIG_FATFS_LONG_FILENAMES
+    ESP_LOGW(TAG, "Warning: Long filenames on SD card are disabled in menuconfig!");
+#endif
+
+    return esp_vfs_fat_sdmmc_mount(BSP_SD_MOUNT_POINT, cfg->host, cfg->slot.sdmmc, cfg->mount, &bsp_sdcard);
+}
+
+esp_err_t bsp_sdcard_sdspi_mount(bsp_sdcard_cfg_t *cfg)
+{
+    sdmmc_host_t sdhost = {0};
+    sdspi_device_config_t sdslot = {0};
     const esp_vfs_fat_sdmmc_mount_config_t mount_config = {
 #ifdef CONFIG_BSP_SD_FORMAT_ON_MOUNT_FAIL
         .format_if_mount_failed = true,
@@ -205,23 +302,71 @@ esp_err_t bsp_sdcard_mount(void)
         .max_files = 5,
         .allocation_unit_size = 16 * 1024
     };
+    assert(cfg);
 
-    sdmmc_host_t host = SDMMC_HOST_DEFAULT();
-    sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
-    slot_config.width = 4;
-    slot_config.cmd = BSP_SD_CMD;
-    slot_config.clk = BSP_SD_CLK;
-    slot_config.d0 = BSP_SD_D0;
-    slot_config.d1 = BSP_SD_D1;
-    slot_config.d2 = BSP_SD_D2;
-    slot_config.d3 = BSP_SD_D3;
+    gpio_config_t power_gpio_config = {
+        .mode = GPIO_MODE_OUTPUT,
+        .pin_bit_mask = 1ULL << BSP_SD_POWER
+    };
+    ESP_ERROR_CHECK(gpio_config(&power_gpio_config));
 
-    return esp_vfs_fat_sdmmc_mount(BSP_SD_MOUNT_POINT, &host, &slot_config, &mount_config, &bsp_sdcard);
+    /* SD card power on first */
+    ESP_ERROR_CHECK(gpio_set_level(BSP_SD_POWER, 0));
+
+    ESP_LOGD(TAG, "Initialize SPI bus");
+    const spi_bus_config_t buscfg = {
+        .sclk_io_num     = BSP_SD_SPI_CLK,
+        .mosi_io_num     = BSP_SD_SPI_MOSI,
+        .miso_io_num     = BSP_SD_SPI_MISO,
+        .quadwp_io_num   = GPIO_NUM_NC,
+        .quadhd_io_num   = GPIO_NUM_NC,
+        .max_transfer_sz = 4000,
+    };
+    ESP_RETURN_ON_ERROR(spi_bus_initialize(BSP_SDSPI_HOST, &buscfg, SPI_DMA_CH_AUTO), TAG, "SPI init failed");
+    spi_sd_initialized = true;
+
+    if (!cfg->mount) {
+        cfg->mount = &mount_config;
+    }
+
+    if (!cfg->host) {
+        bsp_sdcard_get_sdspi_host(SDMMC_HOST_SLOT_0, &sdhost);
+        cfg->host = &sdhost;
+    }
+
+    if (!cfg->slot.sdspi) {
+        bsp_sdcard_sdspi_get_slot(BSP_SDSPI_HOST, &sdslot);
+        cfg->slot.sdspi = &sdslot;
+    }
+
+#if !CONFIG_FATFS_LONG_FILENAMES
+    ESP_LOGW(TAG, "Warning: Long filenames on SD card are disabled in menuconfig!");
+#endif
+
+    return esp_vfs_fat_sdspi_mount(BSP_SD_MOUNT_POINT, cfg->host, cfg->slot.sdspi, cfg->mount, &bsp_sdcard);
+}
+
+esp_err_t bsp_sdcard_mount(void)
+{
+    bsp_sdcard_cfg_t cfg = {0};
+    return bsp_sdcard_sdmmc_mount(&cfg);
 }
 
 esp_err_t bsp_sdcard_unmount(void)
 {
-    return esp_vfs_fat_sdcard_unmount(BSP_SD_MOUNT_POINT, bsp_sdcard);
+    esp_err_t ret = ESP_OK;
+
+    ret |= esp_vfs_fat_sdcard_unmount(BSP_SD_MOUNT_POINT, bsp_sdcard);
+    bsp_sdcard = NULL;
+
+    if (spi_sd_initialized) {
+        ret |= spi_bus_free(BSP_SDSPI_HOST);
+        spi_sd_initialized = false;
+    }
+
+    gpio_reset_pin(BSP_SD_POWER);
+
+    return ret;
 }
 
 esp_codec_dev_handle_t bsp_audio_codec_speaker_init(void)

bsp/esp-box-3/idf_component.yml

@@ -1,5 +1,5 @@
 
-version: "2.0.1"
+version: "3.0.0"
 description: Board Support Package (BSP) for ESP32-S3-BOX-3
 url: https://github.com/espressif/esp-bsp/tree/master/bsp/esp-box-3
 

bsp/esp-box-3/include/bsp/esp-box-3.h

@@ -16,6 +16,8 @@
 #include "driver/i2s_std.h"
 #include "driver/i2c_master.h"
 #include "driver/sdmmc_host.h"
+#include "driver/sdspi_host.h"
+#include "esp_vfs_fat.h"
 #include "esp_codec_dev.h"
 #include "iot_button.h"
 #include "bsp/config.h"
@@ -73,7 +75,7 @@
 #define BSP_BUTTON_CONFIG_IO  (GPIO_NUM_0)
 #define BSP_BUTTON_MUTE_IO    (GPIO_NUM_1)
 
-/* SD card */
+/* uSD card MMC */
 #define BSP_SD_D0             (GPIO_NUM_9)
 #define BSP_SD_D1             (GPIO_NUM_13)
 #define BSP_SD_D2             (GPIO_NUM_42)
@@ -83,6 +85,12 @@
 #define BSP_SD_DET            (GPIO_NUM_NC)
 #define BSP_SD_POWER          (GPIO_NUM_43)
 
+/* uSD card SPI */
+#define BSP_SD_SPI_MISO       (GPIO_NUM_9)
+#define BSP_SD_SPI_CS         (GPIO_NUM_12)
+#define BSP_SD_SPI_MOSI       (GPIO_NUM_14)
+#define BSP_SD_SPI_CLK        (GPIO_NUM_11)
+
 /* PMOD */
 /*
  * PMOD interface (peripheral module interface) is an open standard defined by Digilent Inc.
@@ -284,7 +292,16 @@ esp_err_t bsp_spiffs_unmount(void);
  * @attention IO2 is also routed to RGB LED and push button
  **************************************************************************************************/
 #define BSP_SD_MOUNT_POINT      CONFIG_BSP_SD_MOUNT_POINT
-extern sdmmc_card_t *bsp_sdcard;
+#define BSP_SDSPI_HOST          (SPI2_HOST)
+
+typedef struct {
+    const esp_vfs_fat_sdmmc_mount_config_t *mount;
+    sdmmc_host_t *host;
+    union {
+        const sdmmc_slot_config_t   *sdmmc;
+        const sdspi_device_config_t *sdspi;
+    } slot;
+} bsp_sdcard_cfg_t;
 
 /**
  * @brief Mount microSD card to virtual file system
@@ -311,6 +328,73 @@ esp_err_t bsp_sdcard_mount(void);
  */
 esp_err_t bsp_sdcard_unmount(void);
 
+/**
+ * @brief Get SD card handle
+ *
+ * @return SD card handle
+ */
+sdmmc_card_t *bsp_sdcard_get_handle(void);
+
+/**
+ * @brief Get SD card MMC host config
+ *
+ * @param slot SD card slot
+ * @param config Structure which will be filled
+ */
+void bsp_sdcard_get_sdmmc_host(const int slot, sdmmc_host_t *config);
+
+/**
+ * @brief Get SD card SPI host config
+ *
+ * @param slot SD card slot
+ * @param config Structure which will be filled
+ */
+void bsp_sdcard_get_sdspi_host(const int slot, sdmmc_host_t *config);
+
+/**
+ * @brief Get SD card MMC slot config
+ *
+ * @param slot SD card slot
+ * @param config Structure which will be filled
+ */
+void bsp_sdcard_sdmmc_get_slot(const int slot, sdmmc_slot_config_t *config);
+
+/**
+ * @brief Get SD card SPI slot config
+ *
+ * @param spi_host SPI host ID
+ * @param config Structure which will be filled
+ */
+void bsp_sdcard_sdspi_get_slot(const spi_host_device_t spi_host, sdspi_device_config_t *config);
+
+/**
+ * @brief Mount microSD card to virtual file system (MMC mode)
+ *
+ * @param cfg SD card configuration
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
+ *      - ESP_ERR_NO_MEM if memory cannot be allocated
+ *      - ESP_FAIL if partition cannot be mounted
+ *      - other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
+ */
+esp_err_t bsp_sdcard_sdmmc_mount(bsp_sdcard_cfg_t *cfg);
+
+/**
+ * @brief Mount microSD card to virtual file system (SPI mode)
+ *
+ * @param cfg SD card configuration
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
+ *      - ESP_ERR_NO_MEM if memory cannot be allocated
+ *      - ESP_FAIL if partition cannot be mounted
+ *      - other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
+ */
+esp_err_t bsp_sdcard_sdspi_mount(bsp_sdcard_cfg_t *cfg);
+
 /**************************************************************************************************
  *
  * LCD interface

bsp/esp32_azure_iot_kit/CMakeLists.txt

@@ -2,6 +2,6 @@ idf_component_register(
     SRCS "esp32_azure_iot_kit.c"
     INCLUDE_DIRS "include"
     PRIV_INCLUDE_DIRS "priv_include"
-    REQUIRES driver esp_lcd
-    PRIV_REQUIRES fatfs spiffs
+    REQUIRES driver esp_lcd fatfs
+    PRIV_REQUIRES spiffs
 )