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

docs: peripherals: update SD related docs for ESP32-S3

Browse Source
This commit is contained in:
Ivan Grokhotkov 2022-01-07 18:20:04 +01:00
parent bbe8aabca0
commit ee1b48163f
4 changed files with 211 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/api-reference/peripherals/index.rst
View File

@ -20,7 +20,7 @@ Peripherals API
:SOC_MCPWM_SUPPORTED: mcpwm
:SOC_PCNT_SUPPORTED: pcnt
:SOC_RMT_SUPPORTED: rmt
:esp32 or esp32s3: sd_pullup_requirements
:SOC_SDMMC_HOST_SUPPORTED: sd_pullup_requirements
:SOC_SDMMC_HOST_SUPPORTED: sdmmc_host
sdspi_host
:SOC_SDIO_SLAVE_SUPPORTED: sdio_slave

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

@ -1,21 +1,11 @@
SD Pull-up Requirements
=======================
.. only:: esp32c3
.. warning::
This document is not updated for ESP32-C3 yet.
.. only:: esp32s3
.. warning::
This document is not updated for ESP32-S3 yet.
Espressif hardware products are designed for multiple use cases which may require different pull states on pins. For this reason, the pull state of particular pins on certain products will need to be adjusted to provide the pull-ups required in the SD bus.
SD pull-up requirements apply to cases where {IDF_TARGET_NAME} uses the SPI controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. Slaves should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent SD cards from entering a wrong state.
SD pull-up requirements apply to cases where {IDF_TARGET_NAME} uses the SPI or SDMMC controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. SD cards and SDIO devices should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent them from entering a wrong state.
.. only:: esp32
By default, the MTDI bootstrapping pin is incompatible with the DAT2 line pull-up if the flash voltage is 3.3 V. For more information, see :ref:`mtdi_strapping_pin` below.
@ -53,11 +43,18 @@ Systems on a Chip (SoCs)
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`no_pull-up_on_gpio12`
.. only:: esp32s2
.. only:: SOC_SDMMC_USE_GPIO_MATRIX
.. note::
{IDF_TARGET_NAME} SDMMC host controller allows using any of GPIOs for any of SD interface signals. However, it is recommended to avoid using strapping GPIOs, GPIOs with internal weak pull-downs and GPIOs commonly used for other purposes to prevent conflicts:
No chips listed for ESP32-S2 yet.
.. only:: esp32s3
- GPIO0 (strapping pin)
- GPIO45, GPIO46 (strapping pins, internal weak pulldown)
- GPIO26 - GPIO32 (commonly used for SPI Flash and PSRAM)
- GPIO33 - GPIO37 (when using chips and modules with Octal SPI Flash or Octal PSRAM)
- GPIO43, GPIO44 (GPIOs used for UART0 by default)
- GPIO19, GPIO20 (GPIOs used for USB by default)
Systems in Packages (SIP)
@ -71,13 +68,6 @@ Systems in Packages (SIP)
- :ref:`strapping_conflicts_dat2`
.. only:: esp32s2
.. note::
No chips listed for ESP32-S2 yet.
Modules
^^^^^^^
@ -97,12 +87,6 @@ Modules
- :ref:`sd_pull-up_no_pull-ups`
- :ref:`strapping_conflicts_dat2`
.. only:: esp32s2
.. note::
No chips listed for ESP32-S2 yet.
.. _sdio_dev_kits:
@ -146,12 +130,23 @@ Development Boards
- Required pull-ups are provided
- :ref:`pull-up_conflicts_on_gpio13`
.. only:: esp32s2
.. only:: esp32s3
.. note::
- ESP32-S3-DevKitC-1
No chips listed for ESP32-S2 yet.
- :ref:`sd_pull-up_no_pull-ups`
- ESP32-S3-USB-OTG
- The board may be used in 1-line and 4-line SD mode or SPI mode.
- Required pull-ups are provided on GPIOs 33-38.
- ESP32-S3-EYE
- The board is limited to 1-line SD mode.
- Required pull-ups are provided on GPIOs 38-40.
.. only:: SOC_SDIO_SLAVE_SUPPORTED
Non-Espressif Hosts
^^^^^^^^^^^^^^^^^^^
@ -169,9 +164,10 @@ No Pull-ups
If you use a development board without pull-ups, you can do the following:
- If your host and slave device are on seperate boards, replace one of them with a board that has pull-ups. For the list of Espressif's development boards with pull-ups, go to :ref:`sdio_dev_kits`.
- If your host and slave device are on separate boards, replace one of them with a board that has pull-ups. For the list of Espressif's development boards with pull-ups, go to :ref:`sdio_dev_kits`.
- Attach external pull-ups by connecting each pin which requires a pull-up to VDD via a 10 kOhm resistor.
.. only:: esp32
.. _pull-up_conflicts_on_gpio13:
@ -268,14 +264,14 @@ If the above solutions do not work for you, please determine if it is the host o
Related Information
-------------------
.. only:: esp32
.. _mtdi_strapping_pin:
MTDI Strapping Pin
^^^^^^^^^^^^^^^^^^
MTDI (GPIO12) is used as a bootstrapping pin to select the output voltage of an internal regulator (VDD_SDIO) which powers the flash chip. This pin has an internal pull-down, so, if left unconnected, it will read low at startup, which will lead to selecting the default 3.3 V operation.
.. only:: esp32
MTDI (GPIO12) is used as a bootstrapping pin to select the output voltage of an internal regulator (VDD_SDIO) which powers the flash chip. This pin has an internal pull-down, so, if left unconnected, it will read low level at startup, which will lead to selecting the default 3.3 V operation.
All ESP32-WROVER modules, excluding ESP32-WROVER-B, use 1.8 V flash and have internal pull-ups on GPIO12. Other modules that use 3.3 V flash have no pull-ups on the GPIO12 pin, and this pin is slightly pulled down internally.

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

@ -1,18 +1,6 @@
SDIO Card Slave Driver
======================
.. only:: esp32c3
.. warning::
This document is not updated for ESP32-C3 yet.
.. only:: esp32s3
.. warning::
This document is not updated for ESP32-S3 yet.
Overview
--------

64
docs/en/api-reference/peripherals/sdmmc_host.rst
View File

@ -1,28 +1,17 @@
SDMMC Host Driver
=================
.. only:: esp32c3
.. warning::
This document is not updated for ESP32-C3 yet.
.. only:: esp32s3
.. warning::
This document is not updated for ESP32-S3 yet.
Overview
--------
ESP32's SDMMC host peripheral has two slots:
{IDF_TARGET_NAME}'s SDMMC host peripheral has two slots. Each slot can be used independently to connect to an SD card, SDIO device or eMMC chip.
.. only:: esp32
- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
Pin mappings of these slots are given in the table below.
The slots are connected to {IDF_TARGET_NAME} GPIOs using IO MUX. Pin mappings of these slots are given in the table below.
+--------+-------------+-------------+
| Signal | Slot 0 | Slot 1 |
@ -52,13 +41,18 @@ Pin mappings of these slots are given in the table below.
| WP | any input via GPIO matrix |
+--------+---------------------------+
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``cd`` and ``wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt.
.. warning::
Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly.
.. only:: SOC_SDMMC_USE_GPIO_MATRIX
Both slots (:c:macro:`SDMMC_HOST_SLOT_0`, :c:macro:`SDMMC_HOST_SLOT_1`) support 1-, 4- and 8-line SD interface. The slots are connected to {IDF_TARGET_NAME} GPIOs using GPIO matrix. This means that any GPIO may be used for each of the SD card signals.
Supported Speed Modes
---------------------
@ -105,6 +99,44 @@ To configure the bus width, set the ``width`` field of :cpp:class:`sdmmc_slot_co
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
slot.width = 1;
.. only:: SOC_SDMMC_USE_GPIO_MATRIX
Configuring GPIOs
-----------------
{IDF_TARGET_NAME} SDMMC Host can be configured to use arbitrary GPIOs for each of the signals. Configuration is performed by setting members of :cpp:class:`sdmmc_slot_config_t` structure. For example, to use GPIOs 1-6 for CLK, CMD, D0 - D3 signals, respectively::
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
slot.clk = GPIO_NUM_1;
slot.cmd = GPIO_NUM_2;
slot.d0 = GPIO_NUM_3;
slot.d1 = GPIO_NUM_4;
slot.d2 = GPIO_NUM_5;
slot.d3 = GPIO_NUM_6;
It is also possible to configure Card Detect and Write Protect pins. Similar to other signals, set ``cd`` and ``wp`` members of the same structure::
slot.cd = GPIO_NUM_7;
slot.wp = GPIO_NUM_8;
``SDMMC_SLOT_CONFIG_DEFAULT`` sets both to ``GPIO_NUM_NC``, meaning that by default the signals are not used.
Once :cpp:class:`sdmmc_slot_config_t` structure is initialized this way, you can use it when calling :cpp:func:`sdmmc_host_init_slot` or one of the higher level functions, such as :cpp:func:`esp_vfs_fat_sdmmc_mount`.
DDR Mode for eMMC chips
-----------------------
By default, DDR mode will be used if:
- SDMMC host frequency is set to :c:macro:`SDMMC_FREQ_HIGHSPEED` in :cpp:class:`sdmmc_host_t` structure, and
- eMMC chip reports DDR mode support in its CSD register
DDR mode places higher requirements for signal integrity. To disable DDR mode while keeping :c:macro:`SDMMC_FREQ_HIGHSPEED` frequency, clear :c:macro:`SDMMC_HOST_FLAG_DDR` bit in ``flags`` field of :cpp:class:`sdmmc_host_t`::
sdmmc_host_t host = SDMMC_HOST_DEFAULT();
host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
host.flags &= ~SDMMC_HOST_FLAG_DDR;
See also
--------