examples: sdmmc: re-enable for ESP32-S3, add Kconfig options for pins

examples/storage/sd_card/sdmmc/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32|
-| ----------------- | ---- |
+| Supported Targets | ESP32 | ESP32-S3 |
+| ----------------- | ----- | -------- |
 
 # SD Card example (SDMMC)
 
@@ -9,7 +9,7 @@ This example demonstrates how to use an SD card with an ESP device. Example does
 
 1. Use an "all-in-one" `esp_vfs_fat_sdmmc_mount` function to:
     - initialize SDMMC peripheral,
-    - probe and initialize the card connected to SD/MMC slot 1 (HS2_CMD, HS2_CLK, HS2_D0, HS2_D1, HS2_D2, HS2_D3 lines),
+    - probe and initialize an SD card,
     - mount FAT filesystem using FATFS library (and format card, if the filesystem cannot be mounted),
     - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used.
 2. Print information about the card, such as name, type, capacity, and maximum supported frequency.
@@ -17,13 +17,21 @@ This example demonstrates how to use an SD card with an ESP device. Example does
 4. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function.
 5. Open renamed file for reading, read back the line, and print it to the terminal.
 
-This example support SD (SDSC, SDHC, SDXC) cards and eMMC chips.
+This example supports SD (SDSC, SDHC, SDXC) cards and eMMC chips.
 
-## Hardware connection
+## Hardware
 
-This example runs on ESP-WROVER-KIT boards without any extra modifications required, only the SD card needs to be inserted into the slot.
+This example requires an ESP32 or ESP32-S3 development board with an SD card slot and an SD card.
 
-Other ESP32 development boards need to be connected to SD card as follows:
+Although it is possible to connect an SD card breakout adapter, keep in mind that connections using breakout cables are often unreliable and have poor signal integrity. You may need to use lower clock frequency when working with SD card breakout adapters.
+
+This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.
+
+### Pin assignments for ESP32
+
+On ESP32, SDMMC peripheral is connected to specific GPIO pins using the IO MUX. GPIO pins cannot be customized. Please see the table below for the pin connections.
+
+When using an ESP-WROVER-KIT board, this example runs without any extra modifications required. Only an SD card needs to be inserted into the slot.
 
 ESP32 pin     | SD card pin | Notes
 --------------|-------------|------------
@@ -34,8 +42,32 @@ GPIO4         | D1          | not used in 1-line SD mode; 10k pullup in 4-line S
 GPIO12 (MTDI) | D2          | not used in 1-line SD mode; 10k pullup in 4-line SD mode (see Note about GPIO12 below!)
 GPIO13 (MTCK) | D3          | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup
 
-This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.
 
+### Pin assignments for ESP32-S3
+
+On ESP32-S3, SDMMC peripheral is connected to GPIO pins using GPIO matrix. This allows arbitrary GPIOs to be used to connect an SD card. In this example, GPIOs can be configured in two ways:
+
+1. Using menuconfig: Run `idf.py menuconfig` in the project directory and open "SD/MMC Example Configuration" menu.
+2. In the source code: See the initialization of ``sdmmc_slot_config_t slot_config`` structure in the example code.
+
+The table below lists the default pin assignments.
+
+When using an ESP32-S3-USB-OTG board, this example runs without any extra modifications required. Only an SD card needs to be inserted into the slot.
+
+ESP32-S3 pin  | SD card pin | Notes
+--------------|-------------|------------
+GPIO36        | CLK         | 10k pullup
+GPIO35        | CMD         | 10k pullup
+GPIO37        | D0          | 10k pullup
+GPIO38        | D1          | not used in 1-line SD mode; 10k pullup in 4-line mode
+GPIO33        | D2          | not used in 1-line SD mode; 10k pullup in 4-line mode
+GPIO34        | D3          | not used in 1-line SD mode, but card's D3 pin must have a 10k pullup
+
+### 4-line and 1-line SD modes
+
+By default, this example uses 4 line SD mode, utilizing 6 pins: CLK, CMD, D0 - D3. It is possible to use 1-line mode (CLK, CMD, D0) by changing "SD/MMC bus width" in the example configuration menu (see `CONFIG_EXAMPLE_SDMMC_BUS_WIDTH_1`).
+
+Note that even if card's D3 line is not connected to the ESP chip, it still has to be pulled up, otherwise the card will go into SPI protocol mode.
 
 ### Note about GPIO2 (ESP32 only)
 
@@ -67,18 +99,6 @@ See [the document about pullup requirements](https://docs.espressif.com/projects
 
 ## How to use example
 
-### 4-line and 1-line SD modes
-
-By default, example code uses the following initializer for SDMMC slot configuration:
-
-```c++
-sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
-```
-
-Among other things, this sets `slot_config.width = 0`, which means that SD/MMC driver will use the maximum bus width supported by the slot. For slot 1, it will switch to 4-line mode when initializing the card (initial communication always happens in 1-line mode). If some of the card's D1, D2, D3 pins are not connected to the ESP32, set `slot_config.width = 1` — then the SD/MMC driver will not attempt to switch to 4-line mode.
-
-Note that even if card's D3 line is not connected to the ESP32, it still has to be pulled up, otherwise the card will go into SPI protocol mode.
-
 ### Build and flash
 
 Build the project and flash it to the board, then run monitor tool to view serial output:

examples/storage/sd_card/sdmmc/main/Kconfig.projbuild

@@ -1,4 +1,4 @@
-menu "SD Card Example menu"
+menu "SD/MMC Example Configuration"
 
     config EXAMPLE_FORMAT_IF_MOUNT_FAILED
         bool "Format the card if mount failed"
@@ -6,4 +6,52 @@ menu "SD Card Example menu"
         help
             If this config item is set, format_if_mount_failed will be set to true and the card will be formatted if
             the mount has failed.
+
+    choice EXAMPLE_SDMMC_BUS_WIDTH
+        prompt "SD/MMC bus width"
+        default EXAMPLE_SDMMC_BUS_WIDTH_4
+        help
+            Select the bus width of SD or MMC interface.
+            Note that even if 1 line mode is used, D3 pin of the SD card must have a pull-up resistor connected.
+            Otherwise the card may enter SPI mode, the only way to recover from which is to cycle power to the card.
+
+        config EXAMPLE_SDMMC_BUS_WIDTH_4
+            bool "4 lines (D0 - D3)"
+
+        config EXAMPLE_SDMMC_BUS_WIDTH_1
+            bool "1 line (D0)"
+    endchoice
+
+    if SOC_SDMMC_USE_GPIO_MATRIX
+
+        config EXAMPLE_PIN_CMD
+            int "CMD GPIO number"
+            default 35 if IDF_TARGET_ESP32S3
+
+        config EXAMPLE_PIN_CLK
+            int "CLK GPIO number"
+            default 36 if IDF_TARGET_ESP32S3
+
+        config EXAMPLE_PIN_D0
+            int "D0 GPIO number"
+            default 37 if IDF_TARGET_ESP32S3
+
+        if EXAMPLE_SDMMC_BUS_WIDTH_4
+
+            config EXAMPLE_PIN_D1
+                int "D1 GPIO number"
+                default 38 if IDF_TARGET_ESP32S3
+
+            config EXAMPLE_PIN_D2
+                int "D2 GPIO number"
+                default 33 if IDF_TARGET_ESP32S3
+
+            config EXAMPLE_PIN_D3
+                int "D3 GPIO number"
+                default 34 if IDF_TARGET_ESP32S3
+
+        endif  # EXAMPLE_SDMMC_BUS_WIDTH_4
+
+    endif  # SOC_SDMMC_USE_GPIO_MATRIX
+
 endmenu

examples/storage/sd_card/sdmmc/main/sd_card_example_main.c

@@ -52,19 +52,25 @@ void app_main(void)
     // Modify slot_config.gpio_cd and slot_config.gpio_wp if your board has these signals.
     sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
 
-    // To use 1-line SD mode, change this to 1:
+    // Set bus width to use:
+#ifdef CONFIG_EXAMPLE_SDMMC_BUS_WIDTH_4
     slot_config.width = 4;
+#else
+    slot_config.width = 1;
+#endif
 
     // On chips where the GPIOs used for SD card can be configured, set them in
     // the slot_config structure:
-#ifdef SOC_SDMMC_USE_GPIO_MATRIX
-    slot_config.clk = GPIO_NUM_14;
-    slot_config.cmd = GPIO_NUM_15;
-    slot_config.d0 = GPIO_NUM_2;
-    slot_config.d1 = GPIO_NUM_4;
-    slot_config.d2 = GPIO_NUM_12;
-    slot_config.d3 = GPIO_NUM_13;
-#endif
+#ifdef CONFIG_SOC_SDMMC_USE_GPIO_MATRIX
+    slot_config.clk = CONFIG_EXAMPLE_PIN_CLK;
+    slot_config.cmd = CONFIG_EXAMPLE_PIN_CMD;
+    slot_config.d0 = CONFIG_EXAMPLE_PIN_D0;
+#ifdef CONFIG_EXAMPLE_SDMMC_BUS_WIDTH_4
+    slot_config.d1 = CONFIG_EXAMPLE_PIN_D1;
+    slot_config.d2 = CONFIG_EXAMPLE_PIN_D2;
+    slot_config.d3 = CONFIG_EXAMPLE_PIN_D3;
+#endif  // CONFIG_EXAMPLE_SDMMC_BUS_WIDTH_4
+#endif  // CONFIG_SOC_SDMMC_USE_GPIO_MATRIX
 
     // Enable internal pullups on enabled pins. The internal pullups
     // are insufficient however, please make sure 10k external pullups are