1SDMMC Host Driver
2=================
3
4Overview
5--------
6
7{IDF_TARGET_NAME}'s SDMMC host peripheral has two slots. Each slot can be used independently to connect to an SD card, SDIO device or eMMC chip.
8
9.. only:: esp32
10
11    - Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
12    - Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
13
14    The slots are connected to {IDF_TARGET_NAME} GPIOs using IO MUX. Pin mappings of these slots are given in the table below.
15
16    +--------+-------------+-------------+
17    | Signal | Slot 0      | Slot 1      |
18    +========+=============+=============+
19    | CMD    | GPIO11      | GPIO15      |
20    +--------+-------------+-------------+
21    | CLK    | GPIO6       | GPIO14      |
22    +--------+-------------+-------------+
23    | D0     | GPIO7       | GPIO2       |
24    +--------+-------------+-------------+
25    | D1     | GPIO8       | GPIO4       |
26    +--------+-------------+-------------+
27    | D2     | GPIO9       | GPIO12      |
28    +--------+-------------+-------------+
29    | D3     | GPIO10      | GPIO13      |
30    +--------+-------------+-------------+
31    | D4     | GPIO16      |             |
32    +--------+-------------+-------------+
33    | D5     | GPIO17      |             |
34    +--------+-------------+-------------+
35    | D6     | GPIO5       |             |
36    +--------+-------------+-------------+
37    | D7     | GPIO18      |             |
38    +--------+-------------+-------------+
39    | CD     | any input via GPIO matrix |
40    +--------+---------------------------+
41    | WP     | any input via GPIO matrix |
42    +--------+---------------------------+
43
44    The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``cd`` and ``wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
45
46    .. warning::
47
48        Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
49
50
51.. only:: SOC_SDMMC_USE_GPIO_MATRIX
52
53    Both slots (:c:macro:`SDMMC_HOST_SLOT_0`, :c:macro:`SDMMC_HOST_SLOT_1`) support 1-, 4- and 8-line SD interface. The slots are connected to {IDF_TARGET_NAME} GPIOs using GPIO matrix. This means that any GPIO may be used for each of the SD card signals.
54
55
56Supported Speed Modes
57---------------------
58
59SDMMC Host driver supports the following speed modes:
60
61- Default Speed (20 MHz), 1/4-line (with SD cards), and 1/4/8-line (with 3.3 V eMMC)
62- High Speed (40 MHz), 1/4-line (with SD cards), and 1/4/8-line (with 3.3 V eMMC)
63- High Speed DDR (40 MHz), 4-line (with 3.3 V eMMC)
64
65Speed modes not supported at present:
66
67- High Speed DDR mode, 8-line eMMC
68- UHS-I 1.8 V modes, 4-line SD cards
69
70
71Using the SDMMC Host Driver
72---------------------------
73
74Of all the functions listed below, only the following ones will be used directly by most applications:
75
76- :cpp:func:`sdmmc_host_init`
77- :cpp:func:`sdmmc_host_init_slot`
78- :cpp:func:`sdmmc_host_deinit`
79
80Other functions, such as the ones given below, will be called by the SD/MMC protocol layer via function pointers in the :cpp:class:`sdmmc_host_t` structure:
81
82- :cpp:func:`sdmmc_host_set_bus_width`
83- :cpp:func:`sdmmc_host_set_card_clk`
84- :cpp:func:`sdmmc_host_do_transaction`
85
86
87Configuring Bus Width and Frequency
88-----------------------------------
89
90With 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 the widest bus supported by the card (4 lines for SD, 8 lines for eMMC) and the frequency of 20 MHz.
91
92In the designs where communication at 40 MHz frequency can be achieved, it is possible to increase the bus frequency by changing the ``max_freq_khz`` field of :cpp:class:`sdmmc_host_t`::
93
94    sdmmc_host_t host = SDMMC_HOST_DEFAULT();
95    host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
96
97To configure the bus width, set the ``width`` field of :cpp:class:`sdmmc_slot_config_t`. For example, to set 1-line mode::
98
99    sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
100    slot.width = 1;
101
102.. only:: SOC_SDMMC_USE_GPIO_MATRIX
103
104    Configuring GPIOs
105    -----------------
106
107    {IDF_TARGET_NAME} SDMMC Host can be configured to use arbitrary GPIOs for each of the signals. Configuration is performed by setting members of :cpp:class:`sdmmc_slot_config_t` structure. For example, to use GPIOs 1-6 for CLK, CMD, D0 - D3 signals, respectively::
108
109        sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
110        slot.clk = GPIO_NUM_1;
111        slot.cmd = GPIO_NUM_2;
112        slot.d0 = GPIO_NUM_3;
113        slot.d1 = GPIO_NUM_4;
114        slot.d2 = GPIO_NUM_5;
115        slot.d3 = GPIO_NUM_6;
116
117    It is also possible to configure Card Detect and Write Protect pins. Similar to other signals, set ``cd`` and ``wp`` members of the same structure::
118
119        slot.cd = GPIO_NUM_7;
120        slot.wp = GPIO_NUM_8;
121
122    ``SDMMC_SLOT_CONFIG_DEFAULT`` sets both to ``GPIO_NUM_NC``, meaning that by default the signals are not used.
123
124    Once :cpp:class:`sdmmc_slot_config_t` structure is initialized this way, you can use it when calling :cpp:func:`sdmmc_host_init_slot` or one of the higher level functions, such as :cpp:func:`esp_vfs_fat_sdmmc_mount`.
125
126DDR Mode for eMMC chips
127-----------------------
128
129By default, DDR mode will be used if:
130
131- SDMMC host frequency is set to :c:macro:`SDMMC_FREQ_HIGHSPEED` in :cpp:class:`sdmmc_host_t` structure, and
132- eMMC chip reports DDR mode support in its CSD register
133
134DDR mode places higher requirements for signal integrity. To disable DDR mode while keeping :c:macro:`SDMMC_FREQ_HIGHSPEED` frequency, clear :c:macro:`SDMMC_HOST_FLAG_DDR` bit in ``flags`` field of :cpp:class:`sdmmc_host_t`::
135
136    sdmmc_host_t host = SDMMC_HOST_DEFAULT();
137    host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
138    host.flags &= ~SDMMC_HOST_FLAG_DDR;
139
140
141See also
142--------
143
144See :doc:`SD/SDIO/MMC Driver <../storage/sdmmc>` for the higher level driver which implements the protocol layer.
145
146See :doc:`SD SPI Host Driver <sdspi_host>` for a similar driver which uses the SPI controller and is limited to SD protocol's SPI mode.
147
148See :doc:`sd_pullup_requirements` for pullup support and compatibilities of modules and development kits.
149
150
151API Reference
152-------------
153
154.. include-build-file:: inc/sdmmc_host.inc
155