1| Supported Targets | ESP32 |
2| ----------------- | ----- |
3
4### SDIO Example
5
6## Introduction
7
8These two projects illustrate the SDIO driver (host and slave). The host
9example shows how to initialize a SDIO card, respond to a slave interrupt, as
10well as reading and writing registers and buffers. The slave is a dedicated
11peripheral, providing 8 interrupts, 52 8-bit R/W registers, an input FIFO and
12an output FIFO. The example shows how to configure the driver and use these
13feature.
14
15The host first tell the slave to write the registers to a specified value,
16then reads and prints the value from the slave. Then tell the slave to send 8
17interrupts to the host. Then the host start sending data to the slave FIFO
18and then reads from the slave FIFO in loops.
19
20## Wiring
21
22The SDIO protocol requires at least 4 lines (one more line than SD memory
23protocol): CMD, CLK, DAT0 and DAT1. DAT1 is mandatory for the interrupt. DAT2
24is required if 4-bit mode is used. DAT3 is required in 4-bit mode (connected
25to host), or required by the slave as mode detect in 1-bit mode (pull up). It
26is okay in 1-bit mode to leave DAT3 of host disconnected.
27
28Please run wires between the slave and master to make the example function
29(pins are the same for the host and the slave):
30
31| Signal | GPIO NUM |
32|--------|----------|
33| CLK    | GPIO-14  |
34| CMD    | GPIO-15  |
35| DAT0   | GPIO-2   |
36| DAT1   | GPIO-4   |
37| DAT2   | GPIO-12  |
38| DAT3   | GPIO-13  |
39| Ground | GND      |
40
41CMD and DAT0-3 lines require to be pulled up by 50KOhm resistors even in
421-bit mode. See *Board Compability* below for details. In 1-bit mode, the
43host can make use of DAT2 and DAT3, however the slave should leave them alone
44but pulled up.
45
46Be aware that the example uses lines normally reserved for JTAG. If you're
47using a board with JTAG functions, please remember to remove jumpers
48connecting to the JTAG adapter. The SD peripheral works at a high frequency
49and uses native pins, there's no way to configure it to other pins through
50the GPIO matrix.
51
52Please make sure CMD and DATA lines are pulled up by 50KOhm resistors even in
531-bit mode or SPI mode, which is required by the SD specification.
54
55The 4-bit mode can be configured in the menuconfig. If the 4-bit mode is not
56used, the host will not control the DAT3 line, the slave hardware is
57responsible to pull-up the line (or the slave may run into the SPI mode and
58cause a crash).
59
60The host uses HS mode by default. If the example does not work properly,
61please try connecting two boards by short wires, grounding between two boards
62better or disabling the HS mode in menuconfig.
63
64## Board compatibility
65
661. If you're using a board (e.g. WroverKit v2 and before, PICO, DevKitC)
67    which is not able to drive GPIO2 low on downloading, please remember to
68    disconnect GPIO2 between two boards when downloading the application.
69
702. It is suggested to use the official Wrover Kit as the slave. This is
71    because Wrover Kits have pullups on CMD, DAT0 and DAT1. Otherwise you'll have
72    to connect the pullups manually (or use the Wrover Kit as the host). However,
73    due to a PCB issue, Wrover Kits v3 and earlier have pullup v.s. pulldown
74    conflicts on DAT3 line. You'll have to:
75
76        1. Pull up GPIO13 by resistor of 5KOhm or smaller (2KOhm suggested)
77           in 4-bit mode.
78        2. Pull up, or tie GPIO13 to VDD3.3 in 1-bit mode.
79
80    To help you faster evaluate the SDIO example on devkits without pullups,
81    you can uncomment the pullup enable flags in the initialization code of
82    the app_main of host or slave. This enables internal weak pullups on CMD,
83    DAT0 and DAT1 and DAT3 lines. However please don't rely on internal weak
84    pullups in your own design.
85
863. Moreover, if your slave devkit is using code flash of 3.3V, it is required
87    to pull down DAT2 line to set proper flash voltage. This conflicts with SDIO
88    pullup requirements. Currently devkits using PICO-D4 and Wroom-32 series
89    modules have this problem. You can either:
90
91        - Use Wrover Kit v3 which integrates a Wrover module
92        - Still use PICO-D4 or Wroom-32 Series modules as the slave, however:
93            - Don't connect the DAT2 pin and leave it floating. This means
94                you have to use 1-bit mode in the host. ``SDIO_DAT2_DISABLED``
95                option should be enabled in the menuconfig to avoid using of
96                DAT2. Or:
97            - Burn the EFUSE to force the module using 3.3V as the flash
98                voltage. In this way the voltage of flash doesn't depend on MTDI
99                any more, connect DAT2 to the host and make sure it is pulled up
100                correctly. See document below.
101
102See docs in the programming guide ``api_reference/peripherals/sdio_slave``
103and ``api_reference/peripherals/sd_pullup_requirements`` to see more
104descriptions about pullups and MTDI requirements and solutions of official
105modules and devkits.
106
107## About `esp_serial_slave_link` component used in this example
108
109`esp_serial_slave_link` component in the IDF is used to communicate to a ESP slave device.
110When the `esp_serial_slave_link` device is initialized with an `essl_sdio_config_t` structure,
111the `esp_serial_slave_link` can be used to communicate with an ESP32 SDIO slave.
112