sdmmc: document eMMC support, host features

docs/en/api-reference/peripherals/sdmmc_host.rst

@@ -39,12 +39,25 @@ Pin mappings of these slots are given in the following table:
     | WP     | any input via GPIO matrix |
     +--------+---------------------------+
 
-Card Detect and Write Protect signals can be routed to arbitrary pins using GPIO matrix. To use these pins, set ``gpio_cd`` and ``gpio_wp`` members of :cpp:class:`sdmmc_slot_config_t` structure when calling :cpp:func:`sdmmc_host_init_slot`. Note that it is not advised to specify Card Detect pin when working with SDIO cards, because in ESP32 card detect signal can also trigger SDIO slave interrupt.
+Card Detect and Write Protect signals can be routed to arbitrary pins using GPIO matrix. To use these pins, set ``gpio_cd`` and ``gpio_wp`` members of :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Note that it is not advised to specify Card Detect pin when working with SDIO cards, because in ESP32 card detect signal can also trigger SDIO slave interrupt.
 
 .. warning::
     
     Pins used by slot 0 (``HS1_*``) are also used to connect SPI flash chip in ESP-WROOM32 and ESP32-WROVER modules. These pins can not be shared between SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set Efuses accordingly.
 
+Supported speed modes
+---------------------
+
+SDMMC Host driver supports the following speed modes:
+
+- Default Speed (20MHz), 4-line/1-line (with SD cards), and 8-line (with 3.3V eMMC).
+- High Speed (40MHz), 4-line/1-line (with SD cards), and 8-line (with 3.3V eMMC)
+- High Speed DDR (40MHz), 4-line (with 3.3V eMMC)
+
+Not supported at present are:
+
+- High Speed DDR mode, 8-line eMMC
+- UHS-I 1.8V modes, 4-line SD cards
 
 Using the SDMMC Host driver
 ---------------------------
@@ -53,6 +66,22 @@ Of all the funtions listed below, only :cpp:func:`sdmmc_host_init`, :cpp:func:`s
 
 Other functions, such as :cpp:func:`sdmmc_host_set_bus_width`, :cpp:func:`sdmmc_host_set_card_clk`, and :cpp:func:`sdmmc_host_do_transaction` will be called by the SD/MMC protocol layer via function pointers in :cpp:class:`sdmmc_host_t` structure.
 
+Configuring bus width and frequency
+-----------------------------------
+
+With the default initializers for :cpp:class:`sdmmc_host_t` and :cpp:class:`sdmmc_slot_config_t` (:c:macro:`SDMMC_HOST_DEFAULT` and :c:macro:`SDMMC_SLOT_CONFIG_DEFAULT`), SDMMC Host driver will attempt to use widest bus supported by the card (4 lines for SD, 8 lines for eMMC) and 20MHz frequency.
+
+In designs where communication at 40MHz frequency can be achieved, it is possible to increase the bus frequency to by changing ``max_freq_khz`` field of :cpp:class:`sdmmc_host_t`::
+
+    sdmmc_host_t host = SDMMC_HOST_DEFAULT();
+    host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
+
+To configure bus width, set ``width`` field of :cpp:class:`sdmmc_slot_config_t`. For example, to set 1-line mode::
+
+    sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
+    slot.width = 1;
+
+
 See also
 --------
 

docs/en/api-reference/storage/sdmmc.rst

@@ -4,7 +4,7 @@ SD/SDIO/MMC Driver
 Overview
 --------
 
-SD/SDIO/MMC driver currently supports SD memory and IO cards. Support for MCC/eMMC cards will be added in the future. This protocol level driver builds on top of SDMMC and SD SPI host drivers.
+SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This protocol level driver builds on top of SDMMC and SD SPI host drivers.
 
 SDMMC and SD SPI host drivers (``driver/sdmmc_host.h``) provide APIs to send commands to the slave device(s), send and receive data, and handle error conditions on the bus.
     
@@ -29,11 +29,19 @@ Protocol layer is given :cpp:class:`sdmmc_host_t` structure which describes the
 Usage with SD memory cards
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-1. Call the host driver functions to initialize the host (e.g. :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`). 
+1. Call the host driver functions to initialize the host (e.g. :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`).
 2. Call :cpp:func:`sdmmc_card_init` to initialize the card, passing it host driver information (``host``) and a pointer to :cpp:class:`sdmmc_card_t` structure which will be filled in (``card``).
 3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors`, passing the pointer to card information structure (``card``).
 4. When card is not used anymore, call the host driver function to disable the host peripheral and free resources allocated by the driver (e.g. :cpp:func:`sdmmc_host_deinit`).
 
+Usage with eMMC chips
+^^^^^^^^^^^^^^^^^^^^^
+
+From the perspective of the protocol layer, eMMC memory chips behave the same way as SD memory cards. Because of similarity of the protocol, even though eMMC are chips don't have the "card" form factor, same terminology is used as for SD cards (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips can not be used over SPI, therefore are incompatible with SD SPI host driver.
+
+To initialize eMMC memory and do read/write operations, follow the steps listed above for SD cards.
+
+
 Usage with SDIO cards
 ^^^^^^^^^^^^^^^^^^^^^
 

examples/storage/sd_card/README.md

@@ -12,7 +12,7 @@ This example demonstrates how to use an SD card with ESP32. Example does the fol
 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.
 
-*Note:* despite the name, `sdmmc` component doesn't support MMC/eMMC cards yet. It is also possible to extend `sdmmc` component to support SPI mode with SD cards via SPI peripheral.
+This example support SD (SDSC, SDHC, SDXC) cards and eMMC chips.
 
 ## Hardware
 
@@ -64,13 +64,14 @@ This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG`
 
 ## 4-line and 1-line modes
 
-By default, example code uses the following initializer for SDMMC host peripheral configuration:
+By default, example code uses the following initializer for SDMMC slot configuration:
 
 ```c++
-sdmmc_host_t host = SDMMC_HOST_DEFAULT();
+sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
 ```
 
-Among other things, this sets `host.flags` to `SDMMC_HOST_FLAG_4BIT`, which means that SD/MMC driver 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 `host.flags` to `SDMMC_HOST_FLAG_1BIT` — then the SD/MMC driver will not attempt to switch to 4-line mode.
+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.
 
 ## SPI mode

examples/storage/sd_card/main/sd_card_example_main.c

@@ -47,13 +47,13 @@ void app_main(void)
     ESP_LOGI(TAG, "Using SDMMC peripheral");
     sdmmc_host_t host = SDMMC_HOST_DEFAULT();
 
-    // To use 1-line SD mode, uncomment the following line:
-    // host.flags = SDMMC_HOST_FLAG_1BIT;
-
     // This initializes the slot without card detect (CD) and write protect (WP) signals.
     // 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, uncomment the following line:
+    // slot_config.width = 1;
+
     // GPIOs 15, 2, 4, 12, 13 should have external 10k pull-ups.
     // Internal pull-ups are not sufficient. However, enabling internal pull-ups
     // does make a difference some boards, so we do that here.