alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

sdio_slave: rewrite the doc and highlight efuse-burning as the default option for 3.3V modules

Browse Source
This commit is contained in:
Michael (XIAO Xufeng) 2019-04-09 13:20:22 +08:00
parent 51d811a71c
commit 07166a6b18
3 changed files with 291 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

351
docs/en/api-reference/peripherals/sd_pullup_requirements.rst
View File

@ -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 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_):
: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

84
docs/en/api-reference/peripherals/sdio_slave.rst
View File

@ -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 <https://www.sdcard.org/downloads/pls/>`_), 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.

2
examples/peripherals/sdio/slave/main/Kconfig.projbuild
View File

@ -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 /