From e80e1450accda39c1b278d63042516407eecae1b Mon Sep 17 00:00:00 2001 From: Armando Date: Fri, 6 Jan 2023 16:18:12 +0800 Subject: [PATCH] sdio: c6 doc update --- docs/conf_common.py | 8 +- docs/docs_not_updated/esp32c6.txt | 2 - docs/en/api-reference/peripherals/index.rst | 4 +- .../api-reference/peripherals/sdio_slave.rst | 110 +++++++++++------- .../protocols/esp_sdio_slave_protocol.rst | 5 +- examples/peripherals/sdio/README.md | 43 ++++--- 6 files changed, 104 insertions(+), 68 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index 9f3c820733..4dc4550d93 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -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, diff --git a/docs/docs_not_updated/esp32c6.txt b/docs/docs_not_updated/esp32c6.txt index b22d0c5132..d69f218a22 100644 --- a/docs/docs_not_updated/esp32c6.txt +++ b/docs/docs_not_updated/esp32c6.txt @@ -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 diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 29e82e0a3e..da7e5cee64 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -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 diff --git a/docs/en/api-reference/peripherals/sdio_slave.rst b/docs/en/api-reference/peripherals/sdio_slave.rst index 6723c57d89..2d60cca756 100644 --- a/docs/en/api-reference/peripherals/sdio_slave.rst +++ b/docs/en/api-reference/peripherals/sdio_slave.rst @@ -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 `_), 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 ` -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 - - diff --git a/docs/en/api-reference/protocols/esp_sdio_slave_protocol.rst b/docs/en/api-reference/protocols/esp_sdio_slave_protocol.rst index 6c2577b712..44292b41cc 100644 --- a/docs/en/api-reference/protocols/esp_sdio_slave_protocol.rst +++ b/docs/en/api-reference/protocols/esp_sdio_slave_protocol.rst @@ -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 `_). 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 `_). 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**. - diff --git a/examples/peripherals/sdio/README.md b/examples/peripherals/sdio/README.md index d02b990620..634cf2f5a7 100644 --- a/examples/peripherals/sdio/README.md +++ b/examples/peripherals/sdio/README.md @@ -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: