From 07166a6b18003a350d384f421e983a610ecb2a6c Mon Sep 17 00:00:00 2001 From: "Michael (XIAO Xufeng)" Date: Tue, 9 Apr 2019 13:20:22 +0800 Subject: [PATCH] sdio_slave: rewrite the doc and highlight efuse-burning as the default option for 3.3V modules --- .../peripherals/sd_pullup_requirements.rst | 351 ++++++++++++------ .../api-reference/peripherals/sdio_slave.rst | 84 +++-- .../sdio/slave/main/Kconfig.projbuild | 2 +- 3 files changed, 291 insertions(+), 146 deletions(-) diff --git a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst index 3fd76b0a0..658d94ea9 100644 --- a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst +++ b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst @@ -1,153 +1,268 @@ SD Pullup Requirements ====================== -CMD and DATA lines D0-D3 of the slave should be pulled up by 50KOhm resistor +CMD and DATA lines D0-D3 of the slave should be pulled up by 10 kOhm resistor even in 1-bit mode or SPI mode. The pullups of the slave cards should be connected even if they're not connected to the host. -The MTDI strapping pin is incompatible with DAT2 line pull-up by default -when the code flash is 3.3V. See :ref:`mtdi_strapping_pin` below. +The MTDI strapping pin by default is incompatible with DAT2 line pullup when +the flash is 3.3 V. See :ref:`technical_detail_sdio` below. -Pullup inside Official Modules ------------------------------- +.. _existing_issues_official_modules_sdio: -For Espressif official modules, different weak pullups / pulldowns are -connected to CMD, and DATA pins as below. To use these modules, -these pins are required to be pulled up by 50KOhm resistors, since internal -weak pullups are insufficient. +Possible Issues +--------------- -+-----------------------+-----+--------------------------+------+----------------------+------+ -| GPIO | 15 | 2 | 4 | 12 | 13 | -+=======================+=====+==========================+======+======================+======+ -| Name | CMD | DAT0 | DAT1 | DAT2 | DAT3 | -+-----------------------+-----+--------------------------+------+----------------------+------+ -| At startup | WPU | WPD | WPD | PU for 1.8v flash; | WPU | -| | | | | WPD for 3.3v flash | | -+-----------------------+-----+--------------------------+------+----------------------+------+ -| Strapping requirement | | Low to download to flash | | High for 1.8v flash; | | -| | | | | Low for 3.3v flash | | -+-----------------------+-----+--------------------------+------+----------------------+------+ +Here is a list of Espressif chips, official modules and development kits and +the issues they may have during SDIO development. Since the requirements are +for the pullups on the SD bus, the issues should be resolved no matter if it +is a host or slave. Each issue is linked to its solution. The solution for a +specific issue may be different for host and slave. -- WPU: Weak pullup -- WPD: Weak pulldown -- PU: Pullup inside the module +Official modules are usually without the sufficient pullups on all 6 pins, it +is suggested to select one of the development kits for either host or slave +to provide such pullups. -For Wrover modules, they use 1.8v flash, and have pullup on GPIO12 inside. -For Wroom-32 Series, PICO-D4 modules, they use 3.3v flash, and is weakly -pulled down internally. See :ref:`mtdi_strapping_pin` below. +Chips +^^^^^ -Pullup on Official Devkit (WroverKit) --------------------------------------- + - ESP32 (except D2WD, see `ESP32 datasheet `_): + :ref:`sd_pullup_no_pullups`, whether the strapping conflicts with DAT2 is determined + by the flash you are using. Please see :ref:`strapping_conflicts_dat2` if + your flash chip is 3.3 V. -For official Wrover Kit (till version 3), some of the pullups are provided on -the board as the table below. For other devkits that don't have pullups, -please connect them yourselves. + - ESP32-D2WD: + :ref:`sd_pullup_no_pullups`, :ref:`no_pullup_on_gpio12` -+-----------------------+-----+------+------+------+---------+ -| GPIO | 15 | 2 | 4 | 12 | 13 | -+=======================+=====+======+======+======+=========+ -| Name | CMD | DAT0 | DAT1 | DAT2 | DAT3 | -+-----------------------+-----+------+------+------+---------+ -| Pullup on the Kit | PU | PU | PU | | PU & PD | -+-----------------------+-----+------+------+------+---------+ + - ESP32-PICO-D4: + :ref:`sd_pullup_no_pullups`, :ref:`strapping_conflicts_dat2` -- PU: Pullup -- PD: Pulldown +Modules +^^^^^^^ -The DAT3 pullup conflicts with JTAG pulldown in WroverKit v3 and earlier, please -either: + - ESP32-WROOM-32 Series: + Including ESP32-WROOM-32, ESP32-WROOM-32D, ESP32-WROOM-32U and + ESP32-SOLO-1. -1. pull it up by resistor less than 5KOhm (2kOhm suggested) in 4-bit mode. -2. pull it up or drive it high by host or VDD3.3V in 1-bit mode. + :ref:`sd_pullup_no_pullups`, :ref:`strapping_conflicts_dat2`. -.. _mtdi_strapping_pin: + - ESP32-WROVER Series: + Including ESP32-WROVER and ESP32-WROVER-I. -MTDI strapping pin ------------------- + :ref:`sd_pullup_no_pullups`. -MTDI (GPIO12) is used as a bootstrapping pin to select output voltage of an -internal regulator which powers the flash chip (VDD_SDIO). This pin has an -internal pulldown so if left unconnected it will read low at reset (selecting -default 3.3V operation). When adding a pullup to this pin for SD card -operation, consider the following: + - ESP32-WROVER-B Series: + Including ESP32-WROVER-B and ESP32-WROVER-IB. -- For boards which don't use the internal regulator (VDD_SDIO) to power the - flash, GPIO12 can be pulled high. -- For boards which use 1.8V flash chip, GPIO12 needs to be pulled high at - reset. This is fully compatible with SD card operation. -- On boards which use the internal regulator and a 3.3V flash chip, GPIO12 - must be low at reset. This is incompatible with SD card operation. Please - check the table below to see whether your modules/kits use 3.3v flash. + :ref:`sd_pullup_no_pullups`, :ref:`strapping_conflicts_dat2`. -+-----------------+---------------+--------------------------------------+ -| Module | Flash voltage | DAT2 connections | -+=================+===============+======================================+ -| PICO-D4 | 3.3V | Internal PD, change EFUSE and pullup | -+-----------------+ + or disable DAT2 line* + -| Wroom-32 Series | | | -+-----------------+---------------+--------------------------------------+ -| Wrover | 1.8V | Internal PU, pullup suggested | -+-----------------+---------------+--------------------------------------+ +.. _sdio_dev_kits: -Official devkits of different types and version mount different types of -modules, please refer to the table below to see whether your devkit can -support SDIO slave without steps above. +Development Boards +^^^^^^^^^^^^^^^^^^ -+--------------------------+-----------------+---------------+ -| Devkit | Module | Flash voltage | -+==========================+=================+===============+ -| PICO Kit | PICO-D4 | 3.3V | -+--------------------------+-----------------+ (see steps + -| DevKitC | Wroom-32 Series | below) | -+--------------------------+ + + -| WroverKit v2 and earlier | | | -+--------------------------+-----------------+---------------+ -| WroverKit v3 | Wrover | 1.8V | -+--------------------------+-----------------+---------------+ + - ESP32-PICO-KIT: + Including PICO-KIT v4.1, v4.0 and v3. -If your board requires internal regulator with 3.3v output, to make it -compatible with SD pullup, you can either: + :ref:`sd_pullup_no_pullups`, :ref:`strapping_conflicts_dat2`, + :ref:`gpio2_strapping_pin`. - - **In the case using ESP32 host only**, external pullup can be omitted and an - internal pullup can be enabled using a ``gpio_pullup_en(GPIO_NUM_12);`` call. - Most SD cards work fine when an internal pullup on GPIO12 line is enabled. - Note that if ESP32 experiences a power-on reset while the SD card is - sending data, high level on GPIO12 can be latched into the bootstrapping - register, and ESP32 will enter a boot loop until external reset with - correct GPIO12 level is applied. - - **In the case using ESP32 slave in 1-bit mode**, speicfy - ``SDIO_SLAVE_FLAG_DAT2_DISABLED`` in the slave to avoid slave detecting on - DAT2 line. Note the host will not know 4-bit mode is not supported any more - by the standard CCCR register. You have to tell the host use 1-bit only. - - **For ESP32 host or slave**, another option is to burn the flash voltage - selection efuses. This will permanently select 3.3V output voltage for the - internal regulator, and GPIO12 will not be used as a bootstrapping pin. - Then it is safe to connect a pullup resistor to GPIO12. This option is - suggested for production use. NOTE this cannot be reverted once the EFUSE - is burnt. + - ESP32-DevKitC: + Including ESP32-DevKitC v4 and v2. - The following command can be used to program flash voltage selection efuses **to 3.3V**: + :ref:`sd_pullup_no_pullups`, :ref:`strapping_conflicts_dat2`, + :ref:`gpio2_strapping_pin`. - components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V + - ESP-WROVER-KIT: + v4.1: Have pullups, but :ref:`pullup_conflicts_on_gpio13` , + :ref:`strapping_conflicts_dat2`. - This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and - `XPD_SDIO_REG` efuses. With all three burned to value 1, the internal - VDD_SDIO flash voltage regulator is permanently enabled at 3.3V. See - the technical reference manual for more details. + v3: Have pullups, but :ref:`pullup_conflicts_on_gpio13`. - `espefuse.py` has a `--do-not-confirm` option if running from an automated flashing script. + v2 and v1: Have pullups, but :ref:`pullup_conflicts_on_gpio13`, + :ref:`strapping_conflicts_dat2`, :ref:`gpio2_strapping_pin`. -GPIO2 Strapping pin -------------------- + 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. + + - ESP32-LyraTD-MSC: + :ref:`strapping_conflicts_dat2`. Have pullups. + + - ESP32-LyraT: + Have pullups, but :ref:`pullup_conflicts_on_gpio13` + +Non-Espressif Hosts +^^^^^^^^^^^^^^^^^^^ + +Please make sure that your 3rd party SDIO host has correct pullups for all +the signals. + +Solutions +--------- + +.. _sd_pullup_no_pullups: + +No Pullups +^^^^^^^^^^ + +When developing on boards without pullups, you can either: + +1. If your host and slave are on seperated boards, you can change one of them + to a board with pullups. Please see :ref:`sdio_dev_kits` to find Espressif + official boards with pullups. +2. Connect external pullups to VDD by yourself. Connect these pins without + pullups to the VDD through a 10 kOhm resistor. + +.. _pullup_conflicts_on_gpio13: + +Pullup Conflicts on GPIO13 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The DAT3 of slave may not be properly pulled up. You can either: + +1. Use 1-bit mode, and tie DAT3 of slave to VDD. +2. Use SPI mode. +3. Remove the pulldown resistors on GPIO13; or pull it up by resistor less + than 5 kOhm (2 kOhm suggested); or pull it up or drive it high by host or + VDD3.3V in 1-bit mode. + +.. _strapping_conflicts_dat2: + +Conflicts Between Bootstrap and SDIO on DAT2 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The strapping requirements conflict with SDIO protocol. See +:ref:`mtdi_strapping_pin` for the details of this issue. You can either: + +1. (Recomended) Burn the flash voltage selection eFuses. This will + permanently select 3.3 V output voltage for the internal regulator, and GPIO12 + will not be used as a bootstrapping pin. Then connect a pullup resistor + to GPIO12. + + .. warning:: Burning eFuse is irreversible. The issue list above may be + out of date. Do make sure the module you are burning is using a 3.3 V flash + according to the information on http://www.espressif.com/. If you burn the + 3.3 V eFuses on an 1.8 V module, the module will get broken. + + Run the command below under your IDF folder: + :: + + components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V + + This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and + `XPD_SDIO_REG` eFuses. With all three burned to value 1, the internal + VDD_SDIO flash voltage regulator is permanently set to 3.3 V. You will + see the following log if the burning succeeds: + :: + + espefuse.py v2.6 + Connecting.... + + Enable internal flash voltage regulator (VDD_SDIO) to 3.3 V. + The following eFuses are burned: XPD_SDIO_FORCE, XPD_SDIO_REG, XPD_SDIO_TIEH. + This is an irreversible operation. + Type 'BURN' (all capitals) to continue. + BURN + VDD_SDIO setting complete. + + You can also run ``components/esptool_py/esptool/espefuse.py summary`` to + check the status of the eFuses above. + + `espefuse.py` has a ``--do-not-confirm`` option if running from an + automated flashing script. + + See the ESP32 Technical Reference Manual for more details. + +2. **When using 1-bit mode or SPI mode**, DAT2 signal is not needed (though it + still has to be pulled up). If the device works as the host, you can leave + the DAT2 of host floating, and directly connect DAT2 of slave to VDD; or if + the device works as the slave, specify ``SDIO_SLAVE_FLAG_DAT2_DISABLED`` in + the slave app to avoid slave detecting on DAT2 line. Note the host will + not know that 4-bit mode is not supported any more by the standard CCCR + register. You have to forbid the host from using 4-bit mode. + +.. _no_pullup_on_gpio12: + +No Pullup on GPIO12 +^^^^^^^^^^^^^^^^^^^ + +Your module is compatible with the SDIO protocol. Just connect GPIO12 to the +VDD through a 10 kOhm resistor. + +.. _gpio2_strapping_pin: + +Auto-program Not Working (minor issue) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. You may find it unable to enter the UART download mode if you -correctly connect the pullup of SD on GPIO2. For WroverKit v3, there are -dedicated circuits to pulldown the GPIO2 when downloading. For other boards, -one way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the -auto-reset circuit on most development boards will pull GPIO2 low along with -GPIO0, when entering download mode. +correctly connect the pullup of SD on GPIO2. -- Some boards have pulldown and/or LED on GPIO2. LED is usually ok, but - pulldown will interfere with D0 signals and must be removed. Check the - schematic of your development board for anything connected to GPIO2. +Some official kits pull down GPIO2 when downloading. For other boards, you +may try to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset +circuit on most development boards will pull GPIO2 low along with GPIO0, when +entering download mode. (Some boards have pulldown and/or LED on GPIO2. LED +is usually ok, but the pulldown resistor will interfere with D0 signals and +must be removed. Check the schematic of your development board for anything +connected to GPIO2.) + +If the above way is not working, please just turn off the other device and +remove the pullups on GPIO2 when you are programming the slave. + + +.. _technical_detail_sdio: + +Technical Details +----------------- + +.. _mtdi_strapping_pin: + +MTDI Strapping Pin +^^^^^^^^^^^^^^^^^^ + +MTDI (GPIO12) is used as a bootstrapping pin to select output voltage of an +internal regulator which powers the flash chip (VDD_SDIO). This pin has an +internal pulldown so if left unconnected it will read low at startup +(selecting default 3.3 V operation). + +For ESP32-WROVER modules, excluding ESP32-WROVER-B, they use 1.8 V flash, and +have pullup on GPIO12 inside. For other modules, which use 3.3 V flash, have +no pullups on GPIO12, and GPIO12 is weakly pulled down internally. + +When adding a pullup to this pin for SD card operation, consider the +following: + +- For boards which don't use the internal regulator (VDD_SDIO) to power the + flash, GPIO12 can be pulled high. +- For boards which use 1.8 V flash chip, GPIO12 needs to be pulled high at + reset. This is fully compatible with SD card operation. +- On boards which use the internal regulator and a 3.3 V flash chip, GPIO12 + must be low at reset. This is incompatible with SD card operation. Please + check :ref:`existing_issues_official_modules_sdio` to see whether your board + has this issue, and how to solve it. + +Internal Pullups and Strapping Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is never recommended to rely on internal weak pullups for SDIO +communications, since internal weak pullups are insufficient. But information +of the strapping requirements and internal pullups may be useful. For +Espressif official modules, different weak pullups / pulldowns are connected +to CMD, and DATA pins as below. + ++-----------------------+-----+--------------------------+------+-----------------------+------+ +| GPIO | 15 | 2 | 4 | 12 | 13 | ++=======================+=====+==========================+======+=======================+======+ +| Name | CMD | DAT0 | DAT1 | DAT2 | DAT3 | ++-----------------------+-----+--------------------------+------+-----------------------+------+ +| At startup | WPU | WPD | WPD | PU for 1.8 V flash; | WPU | +| | | | | WPD for 3.3 V flash | | ++-----------------------+-----+--------------------------+------+-----------------------+------+ +| Strapping requirement | | Low to download to flash | | High for 1.8 V flash; | | +| | | | | Low for 3.3 V flash | | ++-----------------------+-----+--------------------------+------+-----------------------+------+ + +- WPU: Weak pullup +- WPD: Weak pulldown +- PU: Pullup inside the module \ No newline at end of file diff --git a/docs/en/api-reference/peripherals/sdio_slave.rst b/docs/en/api-reference/peripherals/sdio_slave.rst index 163cf1168..cd01a51d7 100644 --- a/docs/en/api-reference/peripherals/sdio_slave.rst +++ b/docs/en/api-reference/peripherals/sdio_slave.rst @@ -8,42 +8,72 @@ The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below t 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. -+----------+-------+-------+ -| Pin Name | Slot1 | Slot2 | -+ +-------+-------+ -| | GPIO Number | -+==========+=======+=======+ -| CLK | 6 | 14 | -+----------+-------+-------+ -| CMD | 11 | 15 | -+----------+-------+-------+ -| DAT0 | 7 | 2 | -+----------+-------+-------+ -| DAT1 | 8 | 4 | -+----------+-------+-------+ -| DAT2 | 9 | 12 | -+----------+-------+-------+ -| DAT3 | 10 | 13 | -+----------+-------+-------+ - 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. Then the host initialize the slave into SD mode by first -sending CMD0 with DAT3 pin high, while initialize the slave into SPI mode by -sending CMD0 with CS pin (the same pin as DAT3) low. +4-bit or SPI mode. -.. note:: CMD and DATA lines D0-D3 of the card should be pulled up by 50KOhm resistor - even in 1-bit mode or SPI mode. Most official devkits don't meet the pullup - requirements by default, and there are conflicts on strapping pins as well. - Please refer to :doc:`sd_pullup_requirements` to see how to setup your - system correctly. +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 | ++----------+---------------+-------+-------+ + +- 1-bit SD mode: Connect CLK, CMD, DAT0, DAT1 pins and the ground. +- 4-bit SD mode: Connect all pins and the ground. +- SPI mode: Connect SCLK, MOSI, MISO, Interrupt, #CS pins and the ground. + +.. note:: Please check if CMD and DATA lines D0-D3 of the card are properly + pulled up by 10 KOhm resistors. This should be ensured even in 1-bit mode + or SPI mode. Most official modules don't offer these pullups internally. + If you are using official development boards, check + :ref:`existing_issues_official_modules_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:`existing_issues_official_modules_sdio` to + see how to make your modules compatible with the SDIO. + + Here is a list for modules/kits with 3.3 V flash: + + - 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. .. toctree:: :hidden: sd_pullup_requirements +The host initialize the slave into SD mode by first sending CMD0 with DAT3 +pin high, or in SPI mode by sending CMD0 with CS pin (the same pin as DAT3) +low. + After the initialization, the host can enable the 4-bit SD mode by writing CCCR register 0x07 by CMD52. All the bus detection process are handled by the slave peripheral. @@ -97,7 +127,7 @@ SDIO initialization process (Sector 3.1.2 of `SDIO Simplified Specification `_), which is described briefly in :ref:`esp_slave_init`. -However, there's an ESP32-specific upper-level communication protocol upon +Furthermore, there's an ESP32-specific upper-level communication protocol upon the CMD52/CMD53 to Func 1. Please refer to :ref:`esp_slave_protocol_layer`, or example :example:`peripherals/sdio` when programming your host. diff --git a/examples/peripherals/sdio/slave/main/Kconfig.projbuild b/examples/peripherals/sdio/slave/main/Kconfig.projbuild index 82a44877a..b3485bd3c 100644 --- a/examples/peripherals/sdio/slave/main/Kconfig.projbuild +++ b/examples/peripherals/sdio/slave/main/Kconfig.projbuild @@ -2,7 +2,7 @@ menu "Example Configuration" config SDIO_DAT2_DISABLED bool "Disable the DAT2 in SDIO slave" - default y + default n help SDIO slave DAT pin is unfortunately the same pin as MTDI, which controls the flash power voltage. For 3.3v flash devkits / modules /