mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
sdio: c6 doc update
This commit is contained in:
Armando
Armando (Dou Yiwen)
parent
f1de9faa71
commit
e80e1450ac
@ -65,8 +65,7 @@ WIFI_MESH_DOCS = ['api-guides/esp-wifi-mesh.rst',
|
||||
|
||||
COEXISTENCE_DOCS = ['api-guides/coexist.rst']
|
||||
|
||||
SDMMC_DOCS = ['api-reference/peripherals/sdmmc_host.rst',
|
||||
'api-reference/peripherals/sd_pullup_requirements.rst']
|
||||
SDMMC_DOCS = ['api-reference/peripherals/sdmmc_host.rst']
|
||||
|
||||
SDIO_SLAVE_DOCS = ['api-reference/peripherals/sdio_slave.rst',
|
||||
'api-reference/protocols/esp_sdio_slave_protocol.rst']
|
||||
@ -130,6 +129,7 @@ ESP32_DOCS = ['api-reference/system/himem.rst',
|
||||
'security/secure-boot-v1.rst',
|
||||
'api-reference/peripherals/secure_element.rst',
|
||||
'api-reference/peripherals/dac.rst',
|
||||
'api-reference/peripherals/sd_pullup_requirements.rst',
|
||||
'hw-reference/esp32/**',
|
||||
'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS
|
||||
|
||||
@ -145,6 +145,7 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
|
||||
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
|
||||
'api-reference/system/ipc.rst',
|
||||
'api-guides/flash_psram_config.rst',
|
||||
'api-reference/peripherals/sd_pullup_requirements.rst',
|
||||
'api-guides/RF_calibration.rst']
|
||||
|
||||
# No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
|
||||
@ -153,7 +154,8 @@ ESP32C3_DOCS = ['hw-reference/esp32c3/**',
|
||||
|
||||
ESP32C2_DOCS = ['api-guides/RF_calibration.rst']
|
||||
|
||||
ESP32C6_DOCS = ['api-guides/RF_calibration.rst']
|
||||
ESP32C6_DOCS = ['api-guides/RF_calibration.rst',
|
||||
'api-reference/peripherals/sd_pullup_requirements.rst']
|
||||
|
||||
# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
|
||||
conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
|
||||
|
||||
@ -96,7 +96,6 @@ api-reference/peripherals/sdio_slave
|
||||
api-reference/peripherals/touch_pad
|
||||
api-reference/peripherals/adc_calibration
|
||||
api-reference/peripherals/ds
|
||||
api-reference/peripherals/sd_pullup_requirements
|
||||
api-reference/peripherals/index
|
||||
api-reference/peripherals/sdmmc_host
|
||||
api-reference/kconfig
|
||||
@ -178,7 +177,6 @@ api-reference/error-codes
|
||||
api-reference/index
|
||||
api-reference/protocols
|
||||
api-reference/protocols/esp_serial_slave_link
|
||||
api-reference/protocols/esp_sdio_slave_protocol
|
||||
api-reference/protocols/esp_spi_slave_protocol
|
||||
api-reference/protocols/index
|
||||
security
|
||||
|
||||
@ -24,7 +24,9 @@ Peripherals API
|
||||
:SOC_MCPWM_SUPPORTED: mcpwm
|
||||
:SOC_PCNT_SUPPORTED: pcnt
|
||||
:SOC_RMT_SUPPORTED: rmt
|
||||
:SOC_SDMMC_HOST_SUPPORTED: sd_pullup_requirements
|
||||
:esp32: sd_pullup_requirements
|
||||
:esp32s3: sd_pullup_requirements
|
||||
:esp32c6: sd_pullup_requirements
|
||||
:SOC_SDMMC_HOST_SUPPORTED: sdmmc_host
|
||||
sdspi_host
|
||||
:SOC_SDIO_SLAVE_SUPPORTED: sdio_slave
|
||||
|
||||
@ -4,35 +4,57 @@ SDIO Card Slave Driver
|
||||
Overview
|
||||
--------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table.
|
||||
The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run.
|
||||
This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it.
|
||||
|
||||
The SDIO slave can run under 3 modes: SPI, 1-bit SD and 4-bit SD modes, which
|
||||
is detected automatically by the hardware. According to the SDIO
|
||||
specification, CMD and DAT0-3 lines should be pulled up no matter in 1-bit,
|
||||
4-bit or SPI mode.
|
||||
The SDIO slave can run under 3 modes: SPI, 1-bit SD and 4-bit SD modes, which
|
||||
is detected automatically by the hardware. According to the SDIO
|
||||
specification, CMD and DAT0-3 lines should be pulled up no matter in 1-bit,
|
||||
4-bit or SPI mode.
|
||||
|
||||
Connections
|
||||
^^^^^^^^^^^
|
||||
|
||||
+----------+---------------+-------+-------+
|
||||
| Pin Name | Corresponding | Slot1 | Slot2 |
|
||||
+ + pins in SPI +-------+-------+
|
||||
| | mode | GPIO Number |
|
||||
+==========+===============+=======+=======+
|
||||
| CLK | SCLK | 6 | 14 |
|
||||
+----------+---------------+-------+-------+
|
||||
| CMD | MOSI | 11 | 15 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT0 | MISO | 7 | 2 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT1 | Interrupt | 8 | 4 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT2 | N.C. (pullup) | 9 | 12 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT3 | #CS | 10 | 13 |
|
||||
+----------+---------------+-------+-------+
|
||||
.. only:: esp32
|
||||
|
||||
+----------+---------------+-------+-------+
|
||||
| Pin Name | Corresponding | Slot1 | Slot2 |
|
||||
+ + pins in SPI +-------+-------+
|
||||
| | mode | GPIO Number |
|
||||
+==========+===============+=======+=======+
|
||||
| CLK | SCLK | 6 | 14 |
|
||||
+----------+---------------+-------+-------+
|
||||
| CMD | MOSI | 11 | 15 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT0 | MISO | 7 | 2 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT1 | Interrupt | 8 | 4 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT2 | N.C. (pullup) | 9 | 12 |
|
||||
+----------+---------------+-------+-------+
|
||||
| DAT3 | #CS | 10 | 13 |
|
||||
+----------+---------------+-------+-------+
|
||||
|
||||
.. only:: esp32c6
|
||||
|
||||
+----------+--------------------------------+---------------+
|
||||
| Pin Name | Corresponding pins in SPI mode | GPIO Number |
|
||||
+==========+================================+===============+
|
||||
| CLK | SCLK | 19 |
|
||||
+----------+--------------------------------+---------------+
|
||||
| CMD | MOSI | 18 |
|
||||
+----------+--------------------------------+---------------+
|
||||
| DAT0 | MISO | 20 |
|
||||
+----------+--------------------------------+---------------+
|
||||
| DAT1 | Interrupt | 21 |
|
||||
+----------+--------------------------------+---------------+
|
||||
| DAT2 | N.C. (pullup) | 22 |
|
||||
+----------+--------------------------------+---------------+
|
||||
| DAT3 | #CS | 23 |
|
||||
+----------+--------------------------------+---------------+
|
||||
|
||||
- 1-bit SD mode: Connect CLK, CMD, DAT0, DAT1 pins and the ground.
|
||||
- 4-bit SD mode: Connect all pins and the ground.
|
||||
@ -45,23 +67,25 @@ Connections
|
||||
:ref:`compatibility_overview_espressif_hw_sdio` to see whether your
|
||||
development boards have such pullups.
|
||||
|
||||
.. note:: Most official modules have conflicts on strapping pins with the
|
||||
SDIO slave function. If you are using a ESP32 module with 3.3 V flash
|
||||
inside, you have to burn the EFUSE when you are developing on the module
|
||||
for the first time. See :ref:`compatibility_overview_espressif_hw_sdio` to
|
||||
see how to make your modules compatible with the SDIO.
|
||||
.. only:: esp32
|
||||
|
||||
Here is a list for modules/kits with 3.3 V flash:
|
||||
.. note:: Most official modules have conflicts on strapping pins with the
|
||||
SDIO slave function. If you are using a ESP32 module with 3.3 V flash
|
||||
inside, you have to burn the EFUSE when you are developing on the module
|
||||
for the first time. See :ref:`compatibility_overview_espressif_hw_sdio` to
|
||||
see how to make your modules compatible with the SDIO.
|
||||
|
||||
- Modules: ESP32-PICO-D4, ESP32-WROOM-32 series (including ESP32-SOLO-1),
|
||||
ESP32-WROVER-B and ESP32-WROVER-IB
|
||||
- Kits: ESP32-PICO-KIT, ESP32-DevKitC (till v4), ESP32-WROVER-KIT
|
||||
(v4.1 (also known as ESP32-WROVER-KIT-VB), v2, v1 (also known as DevKitJ
|
||||
v1))
|
||||
Here is a list for modules/kits with 3.3 V flash:
|
||||
|
||||
You can tell the version of your ESP23-WROVER-KIT version from the module
|
||||
on it: v4.1 are with ESP32-WROVER-B modules, v3 are with ESP32-WROVER
|
||||
modules, while v2 and v1 are with ESP32-WROOM-32 modules.
|
||||
- Modules: ESP32-PICO-D4, ESP32-WROOM-32 series (including ESP32-SOLO-1),
|
||||
ESP32-WROVER-B and ESP32-WROVER-IB
|
||||
- Kits: ESP32-PICO-KIT, ESP32-DevKitC (till v4), ESP32-WROVER-KIT
|
||||
(v4.1 (also known as ESP32-WROVER-KIT-VB), v2, v1 (also known as DevKitJ
|
||||
v1))
|
||||
|
||||
You can tell the version of your ESP23-WROVER-KIT version from the module
|
||||
on it: v4.1 are with ESP32-WROVER-B modules, v3 are with ESP32-WROVER
|
||||
modules, while v2 and v1 are with ESP32-WROOM-32 modules.
|
||||
|
||||
Refer to :doc:`sd_pullup_requirements` for more technical details of the pullups.
|
||||
|
||||
@ -90,7 +114,7 @@ Terminology
|
||||
The SDIO slave driver uses the following terms:
|
||||
|
||||
- Transfer: a transfer is always started by a command token from the host, and may contain a reply and several data
|
||||
blocks. ESP32 slave software is based on transfers.
|
||||
blocks. {IDF_TARGET_NAME} SDIO slave software is based on transfers.
|
||||
- Sending: slave to host transfers.
|
||||
- Receiving: host to slave transfers.
|
||||
|
||||
@ -109,29 +133,29 @@ The SDIO slave driver uses the following terms:
|
||||
- Requested length: The length requested in one transfer determined by the FIFO address.
|
||||
- Transfer length: The length requested in one transfer determined by the CMD53 byte/block count field.
|
||||
|
||||
.. note:: Requested length is different from the transfer length. ESP32 slave DMA base on the *requested length* rather
|
||||
.. note:: Requested length is different from the transfer length. {IDF_TARGET_NAME} SDIO slave DMA base on the *requested length* rather
|
||||
than the *transfer length*. The *transfer length* should be no shorter than the *requested length*, and the rest
|
||||
part will be filled with 0 (sending) or discard (receiving).
|
||||
|
||||
- Receiving buffer size: The buffer size is pre-defined between the host and the slave before communication starts.
|
||||
Slave application has to set the buffer size during initialization by the ``recv_buffer_size`` member of
|
||||
``sdio_slave_config_t``.
|
||||
- Interrupts: the esp32 slave support interrupts in two directions: from host to slave (called slave interrupts below)
|
||||
- Interrupts: the {IDF_TARGET_NAME} SDIO slave support interrupts in two directions: from host to slave (called slave interrupts below)
|
||||
and from slave to host (called host interrupts below). See more in :ref:`interrupts`.
|
||||
- Registers: specific address in Function 1 access by CMD52 or CMD53.
|
||||
|
||||
Communication with ESP SDIO Slave
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The host should initialize the ESP32 SDIO slave according to the standard
|
||||
The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard
|
||||
SDIO initialization process (Sector 3.1.2 of `SDIO Simplified
|
||||
Specification <https://www.sdcard.org/downloads/pls/>`_), which is described
|
||||
briefly in :ref:`esp_slave_init`.
|
||||
|
||||
Furthermore, there's an ESP32-specific upper-level communication protocol upon the CMD52/CMD53 to
|
||||
Furthermore, there's an {IDF_TARGET_NAME}-specific upper-level communication protocol upon the CMD52/CMD53 to
|
||||
Func 1. Please refer to :ref:`esp_slave_protocol_layer`. There is also a component
|
||||
:doc:`ESP Serial Slave Link </api-reference/protocols/esp_serial_slave_link>`
|
||||
for ESP32 master to communicate with ESP32 SDIO slave, see example :example:`peripherals/sdio`
|
||||
for {IDF_TARGET_NAME} master to communicate with {IDF_TARGET_NAME} SDIO slave, see example :example:`peripherals/sdio`
|
||||
when programming your host.
|
||||
|
||||
|
||||
@ -222,7 +246,7 @@ following functions instead:
|
||||
If non-blocking call is needed, set ``wait=0``. If the ``wait`` is not ``portMAX_DELAY`` (wait until success),
|
||||
application has to check the result to know whether the data is put in to the queue or discard.
|
||||
|
||||
2. Call ``sdio_slave_send_get_finished`` to get and deal with a finished transfer. A buffer should be keep unmodified
|
||||
2. Call ``sdio_slave_send_get_finished`` to get and deal with a finished transfer. A buffer should be kept unmodified
|
||||
until returned from ``sdio_slave_send_get_finished``. This means the buffer is actually sent to the host, rather
|
||||
than just staying in the queue.
|
||||
|
||||
@ -281,5 +305,3 @@ API Reference
|
||||
|
||||
.. include-build-file:: inc/sdio_slave_types.inc
|
||||
.. include-build-file:: inc/sdio_slave.inc
|
||||
|
||||
|
||||
|
||||
@ -39,7 +39,7 @@ The services provided by the SDIO Slave peripheral of the {IDF_TARGET_NAME} chip
|
||||
ESP SDIO Slave Initialization
|
||||
-----------------------------
|
||||
|
||||
The host should initialize the ESP32 SDIO slave according to the standard SDIO initialization process (Section 3.1.2 of `SDIO Simplified Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification as well as below, the SDIO slave is called an (SD)IO card. Here is a brief example of an ESP SDIO Slave initialization process:
|
||||
The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard SDIO initialization process (Section 3.1.2 of `SDIO Simplified Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification as well as below, the SDIO slave is called an (SD)IO card. Here is a brief example of an ESP SDIO Slave initialization process:
|
||||
|
||||
1. SDIO reset
|
||||
CMD52 (Write 0x6=0x8)
|
||||
@ -171,7 +171,7 @@ Interrupts
|
||||
|
||||
SDIO interrupts are "level sensitive". For host interrupts, the slave sends an interrupt by pulling the DAT1 line down at a proper time. The host detects when the interrupt line is pulled down and reads the INT_ST register to determine the source of the interrupt. After that, the host can clear the interrupt bits by writing the INT_CLR register and process the interrupt. The host can also mask unneeded sources by clearing the bits in the INT_ENA register corresponding to the sources. If all the sources are cleared (or masked), the DAT1 line goes inactive.
|
||||
|
||||
On ESP32, the corresponding host_int bits are: bit 0 to bit 7.
|
||||
On {IDF_TARGET_NAME}, the corresponding host_int bits are: bit 0 to bit 7.
|
||||
|
||||
For slave interrupts, the host sends a transfer to write the SLAVE_INT register. Once a bit is set to 1, the slave hardware and the driver will detect it and inform the application.
|
||||
|
||||
@ -199,4 +199,3 @@ To read the slave's sending FIFO, the host should complete the following steps:
|
||||
3. **If new packets are ready, read the PKT_LEN register**. Before reading the packets, determine the length of data to be read. As the host keeps the length of data already read from the slave, subtract this value from PKT_LEN, the result will be the maximum length of data available for reading. If no data has been added to the sending FIFO yet, wait and poll until the slave is ready and update PKT_LEN.
|
||||
4. **Read from the FIFO using CMD53**. Note that the *requested length* should not be greater than calculated at Step 3, and the FIFO address is related to *requested length*.
|
||||
5. **Update the read length**.
|
||||
|
||||
|
||||
@ -26,22 +26,28 @@ Please run wires between the slave and master to make the example function, and
|
||||
|
||||
### Slave
|
||||
|
||||
On ESP32, the pins of SDIO Slave are fixed:
|
||||
On ESP32 / ESP32C6, the pins of SDIO Slave are fixed:
|
||||
|
||||
| Signal | GPIO NUM |
|
||||
|--------|----------|
|
||||
| CLK | GPIO-14 |
|
||||
| CMD | GPIO-15 |
|
||||
| DAT0 | GPIO-2 |
|
||||
| DAT1 | GPIO-4 |
|
||||
| DAT2 | GPIO-12 |
|
||||
| DAT3 | GPIO-13 |
|
||||
| | ESP32 | ESP32C6 |
|
||||
|--------|----------|----------|
|
||||
| Signal | GPIO NUM | GPIO NUM |
|
||||
|--------|----------|----------|
|
||||
| CLK | GPIO-14 | GPIO-19 |
|
||||
| CMD | GPIO-15 | GPIO-18 |
|
||||
| DAT0 | GPIO-2 | GPIO-20 |
|
||||
| DAT1 | GPIO-4 | GPIO-21 |
|
||||
| DAT2 | GPIO-12 | GPIO-22 |
|
||||
| DAT3 | GPIO-13 | GPIO-23 |
|
||||
|
||||
#### Note
|
||||
|
||||
The SD peripheral works at a high frequency
|
||||
and uses native pins, there's no way to configure it to other pins through
|
||||
the GPIO matrix.
|
||||
|
||||
Be aware that these pins are normally reserved for JTAG on ESP32. If you're
|
||||
using a board with JTAG functions, please remember to remove jumpers
|
||||
connecting to the JTAG adapter. The SD peripheral works at a high frequency
|
||||
and uses native pins, there's no way to configure it to other pins through
|
||||
the GPIO matrix.
|
||||
connecting to the JTAG adapter. (ESP32 Only).
|
||||
|
||||
### Host
|
||||
|
||||
@ -72,11 +78,18 @@ please try:
|
||||
|
||||
## Board compatibility
|
||||
|
||||
1. If you're using a board (e.g. WroverKit v2 and before, PICO, DevKitC)
|
||||
Pull-up resistors is needed. As the SD specification and the eMMC datasheet clarify,
|
||||
minimum 10k pull-up resistors are required for the bus IOs to protect the IOs against bus floating issue.
|
||||
Note these pull-up resistors are needed, even if the pin is not used (For example,
|
||||
you use 1-line-mode, the pull-up resistor is still required for the D1 pin).
|
||||
|
||||
Some other notes:
|
||||
|
||||
1. (ESP32 Only) If you're using a board (e.g. WroverKit v2 and before, PICO, DevKitC)
|
||||
which is not able to drive GPIO2 low on downloading, please remember to
|
||||
disconnect GPIO2 between two boards when downloading the application.
|
||||
|
||||
2. It is suggested to use the official Wrover Kit as the slave. This is
|
||||
2. (ESP32 Only) It is suggested to use the official Wrover Kit as the slave. This is
|
||||
because Wrover Kits have pullups on CMD, DAT0 and DAT1. Otherwise you'll have
|
||||
to connect the pullups manually (or use the Wrover Kit as the host). However,
|
||||
due to a PCB issue, Wrover Kits v3 and earlier have pullup v.s. pulldown
|
||||
@ -92,7 +105,7 @@ please try:
|
||||
DAT0 and DAT1 and DAT3 lines. However please don't rely on internal weak
|
||||
pullups in your own design.
|
||||
|
||||
3. Moreover, if your slave devkit is using code flash of 3.3V, it is required
|
||||
3. (ESP32 Only) Moreover, if your slave devkit is using code flash of 3.3V, it is required
|
||||
to pull down DAT2 line to set proper flash voltage. This conflicts with SDIO
|
||||
pullup requirements. Currently devkits using PICO-D4 and Wroom-32 series
|
||||
modules have this problem. You can either:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user