mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-19 14:26:01 -04:00
Merge branch 'doc/sdmmc_emmc_support' into 'master'
docs(sdmmc): update information about eMMC support Closes DOC-8906 See merge request espressif/esp-idf!33022
This commit is contained in:
Ivan Grokhotkov
commit
0a2dc3b2d6
@ -21,9 +21,6 @@ extern "C" {
|
||||
/**
|
||||
* Probe and initialize SD/MMC card using given host
|
||||
*
|
||||
* @note Only SD cards (SDSC and SDHC/SDXC) are supported now.
|
||||
* Support for MMC/eMMC cards will be added later.
|
||||
*
|
||||
* @param host pointer to structure defining host controller
|
||||
* @param out_card pointer to structure which will receive information
|
||||
* about the card when the function completes
|
||||
|
||||
@ -6,7 +6,7 @@ SD/SDIO/MMC Driver
|
||||
Overview
|
||||
--------
|
||||
|
||||
The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips. This is a protocol layer driver (:component_file:`sdmmc/include/sdmmc_cmd.h`) which can be implemented by:
|
||||
The SD/SDIO/MMC driver supports SD memory, SDIO cards, and eMMC chips. This is a protocol layer driver (:component_file:`sdmmc/include/sdmmc_cmd.h`) which can work together with:
|
||||
|
||||
.. list::
|
||||
:SOC_SDMMC_HOST_SUPPORTED: - SDMMC host driver (:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h`), see :doc:`SDMMC Host API <../peripherals/sdmmc_host>` for more details.
|
||||
@ -15,7 +15,7 @@ The SD/SDIO/MMC driver currently supports SD memory, SDIO cards, and eMMC chips.
|
||||
Protocol Layer vs Host Layer
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization flow and variours data transfer command flows. The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.
|
||||
The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization flow and various data transfer command flows. The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.
|
||||
|
||||
Host layer driver(s) implement the protocol layer driver by supporting these functions:
|
||||
|
||||
@ -34,23 +34,31 @@ Application Example
|
||||
|
||||
An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
|
||||
|
||||
Protocol Layer API
|
||||
------------------
|
||||
|
||||
The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions for the implementation driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any.
|
||||
|
||||
Using API with SD Memory Cards
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list::
|
||||
:SOC_SDMMC_HOST_SUPPORTED: - To initialize the SDMMC host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`.¸
|
||||
:SOC_GPSPI_SUPPORTED: - To initialize the SDSPI host, call the host driver functions, e.g., :cpp:func:`sdspi_host_init`, :cpp:func:`sdspi_host_init_slot`.
|
||||
- To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes.
|
||||
- To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure.
|
||||
|
||||
- If the card is not used anymore, call the host driver function to disable the host peripheral and free the resources allocated by the driver (``sdmmc_host_deinit`` for SDMMC or ``sdspi_host_deinit`` for SDSPI).
|
||||
|
||||
.. only:: not SOC_SDMMC_HOST_SUPPORTED
|
||||
|
||||
eMMC Support
|
||||
^^^^^^^^^^^^
|
||||
|
||||
{IDF_TARGET_NAME} does not have an SDMMC Host controller, and can only use SPI protocol for communication with cards. However, eMMC chips cannot be used over SPI. Therefore it is not possible to use eMMC chips with {IDF_TARGET_NAME}.
|
||||
|
||||
.. only:: SOC_SDMMC_HOST_SUPPORTED
|
||||
|
||||
Protocol Layer API
|
||||
------------------
|
||||
|
||||
The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions for the implementation driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any.
|
||||
|
||||
|
||||
Using API with SD Memory Cards
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`.
|
||||
2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes.
|
||||
3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure.
|
||||
4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver.
|
||||
|
||||
|
||||
Using API with eMMC Chips
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -99,10 +107,10 @@ An example which combines the SDMMC driver with the FATFS library is provided in
|
||||
|
||||
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32 SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
|
||||
|
||||
Combo (Memory + IO) Cards
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Combo (Memory + IO) Cards
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The driver does not support SD combo cards. Combo cards are treated as IO cards.
|
||||
The driver does not support SD combo cards. Combo cards are treated as IO cards.
|
||||
|
||||
|
||||
Thread Safety
|
||||
|
||||
@ -6,11 +6,11 @@ SD/SDIO/MMC 驱动程序
|
||||
概述
|
||||
--------
|
||||
|
||||
SD/SDIO/MMC 驱动目前支持 SD 存储器、SDIO 卡和 eMMC 芯片。这是一个协议层驱动 (:component_file:`sdmmc/include/sdmmc_cmd.h`)，可以由以下方式实现：
|
||||
SD/SDIO/MMC 驱动支持 SD 存储器、SDIO 卡和 eMMC 芯片。这是一个协议层驱动 (:component_file:`sdmmc/include/sdmmc_cmd.h`)，可以与以下驱动配合使用：
|
||||
|
||||
.. list::
|
||||
:SOC_SDMMC_HOST_SUPPORTED: - SDMMC 主机驱动 (:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h`)，详情请参阅 :doc:`SDMMC Host API <../peripherals/sdmmc_host>`。
|
||||
:SOC_GPSPI_SUPPORTED: - SDSPI 主机驱动 (:component_file:`esp_driver_sdspi/include/driver/sdspi_host.h`)，详情请参阅 :doc:`SD SPI Host API <../peripherals/sdspi_host>`。
|
||||
:SOC_SDMMC_HOST_SUPPORTED: - SDMMC 主机驱动 (:component_file:`esp_driver_sdmmc/include/driver/sdmmc_host.h`)，详情请参阅 :doc:`SDMMC Host API <../peripherals/sdmmc_host>`。
|
||||
:SOC_GPSPI_SUPPORTED: - SDSPI 主机驱动 (:component_file:`esp_driver_sdspi/include/driver/sdspi_host.h`)，详情请参阅 :doc:`SD SPI Host API <../peripherals/sdspi_host>`。
|
||||
|
||||
协议层与主机层
|
||||
^^^^^^^^^^^^^^
|
||||
@ -34,23 +34,31 @@ SD/SDIO/MMC 驱动目前支持 SD 存储器、SDIO 卡和 eMMC 芯片。这是
|
||||
|
||||
ESP-IDF :example:`storage/sd_card` 目录下提供了 SDMMC 驱动与 FatFs 库组合使用的示例，演示了先初始化卡，然后使用 POSIX 和 C 库 API 向卡读写数据。请参考示例目录下 README.md 文件，查看更多详细信息。
|
||||
|
||||
协议层 API
|
||||
------------------
|
||||
|
||||
协议层具备 :cpp:class:`sdmmc_host_t` 结构体，此结构体描述了 SD/MMC 主机驱动，列出了其功能，并提供指向驱动程序函数的指针。协议层将卡信息储存于 :cpp:class:`sdmmc_card_t` 结构体中。向 SD/MMC 主机发送命令时，协议层使用 :cpp:class:`sdmmc_command_t` 结构体来描述命令、参数、预期返回值和需传输的数据（如有）。
|
||||
|
||||
用于 SD 存储卡的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. list::
|
||||
:SOC_SDMMC_HOST_SUPPORTED: - 初始化 SDMMC 主机，请调用主机驱动函数，例如 :cpp:func:`sdmmc_host_init` 和 :cpp:func:`sdmmc_host_init_slot`。
|
||||
:SOC_GPSPI_SUPPORTED: - 初始化 SDSPI 主机，请调用主机驱动函数，例如 :cpp:func:`sdspi_host_init` 和 :cpp:func:`sdspi_host_init_slot`。
|
||||
- 初始化卡，请调用 :cpp:func:`sdmmc_card_init`，并将参数 ``host`` （主机驱动信息）和参数 ``card`` （指向 :cpp:class:`sdmmc_card_t` 结构体的指针）传递给此函数。函数运行结束后，将会向 :cpp:class:`sdmmc_card_t` 结构体填充该卡的信息。
|
||||
- 读取或写入卡的扇区，请分别调用 :cpp:func:`sdmmc_read_sectors` 和 :cpp:func:`sdmmc_write_sectors`，并将参数 ``card`` （指向卡信息结构的指针）传递给函数。
|
||||
|
||||
- 如果不再使用该卡，请调用主机驱动函数，例如 ``sdmmc_host_deinit`` 或 ``sdspi_host_deinit``，以禁用SDMMC 主机外设或 SDSPI 主机外设，并释放驱动程序分配的资源。
|
||||
|
||||
.. only:: not SOC_SDMMC_HOST_SUPPORTED
|
||||
|
||||
eMMC 芯片支持
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
{IDF_TARGET_NAME} 没有 SDMMC 主机控制器，只能使用 SPI 协议与卡通信。然而，eMMC 芯片不能通过 SPI 使用。因此，无法在 {IDF_TARGET_NAME} 上使用 eMMC 芯片。
|
||||
|
||||
.. only:: SOC_SDMMC_HOST_SUPPORTED
|
||||
|
||||
协议层 API
|
||||
------------------
|
||||
|
||||
协议层具备 :cpp:class:`sdmmc_host_t` 结构体，此结构体描述了 SD/MMC 主机驱动，列出了其功能，并提供指向驱动程序函数的指针。协议层将卡信息储存于 :cpp:class:`sdmmc_card_t` 结构体中。向 SD/MMC 主机发送命令时，协议层使用 :cpp:class:`sdmmc_command_t` 结构体来描述命令、参数、预期返回值和需传输的数据（如有）。
|
||||
|
||||
|
||||
用于 SD 存储卡的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. 初始化主机，请调用主机驱动函数，例如 :cpp:func:`sdmmc_host_init` 和 :cpp:func:`sdmmc_host_init_slot`；
|
||||
2. 初始化卡，请调用 :cpp:func:`sdmmc_card_init`，并将参数 ``host`` （主机驱动信息）和参数 ``card`` （指向 :cpp:class:`sdmmc_card_t` 结构体的指针）传递给此函数。函数运行结束后，将会向 :cpp:class:`sdmmc_card_t` 结构体填充该卡的信息；
|
||||
3. 读取或写入卡的扇区，请分别调用 :cpp:func:`sdmmc_read_sectors` 和 :cpp:func:`sdmmc_write_sectors`，并将参数 ``card`` （指向卡信息结构的指针）传递给函数；
|
||||
4. 如果不再使用该卡，请调用主机驱动函数，例如 :cpp:func:`sdmmc_host_deinit`，以禁用主机外设，并释放驱动程序分配的资源。
|
||||
|
||||
|
||||
用于 eMMC 芯片的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -81,13 +89,13 @@ ESP-IDF :example:`storage/sd_card` 目录下提供了 SDMMC 驱动与 FatFs 库
|
||||
* - 操作
|
||||
- 函数读取
|
||||
- 函数写入
|
||||
* - 使用 IO_RW_DIRECT (CMD52) 读写单个字节。
|
||||
* - 使用 IO_RW_DIRECT (CMD52) 读写单个字节
|
||||
- :cpp:func:`sdmmc_io_read_byte`
|
||||
- :cpp:func:`sdmmc_io_write_byte`
|
||||
* - 使用 IO_RW_EXTENDED (CMD53) 的字节模式读写多个字节。
|
||||
* - 使用 IO_RW_EXTENDED (CMD53) 的字节模式读写多个字节
|
||||
- :cpp:func:`sdmmc_io_read_bytes`
|
||||
- :cpp:func:`sdmmc_io_write_bytes`
|
||||
* - 块模式下，使用 IO_RW_EXTENDED (CMD53) 读写数据块。
|
||||
* - 块模式下，使用 IO_RW_EXTENDED (CMD53) 读写数据块
|
||||
- :cpp:func:`sdmmc_io_read_blocks`
|
||||
- :cpp:func:`sdmmc_io_write_blocks`
|
||||
|
||||
@ -97,12 +105,12 @@ ESP-IDF :example:`storage/sd_card` 目录下提供了 SDMMC 驱动与 FatFs 库
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
如果需要与 ESP32 的 SDIO 从设备通信，请使用 ESSL 组件（ESP 串行从设备链接）。请参阅 :doc:`/api-reference/protocols/esp_serial_slave_link` 和 :example:`peripherals/sdio/host`。
|
||||
如果需要与 ESP32 的 SDIO 从设备通信，请使用 ESSL 组件（ESP 串行从设备链接）。请参阅 :doc:`/api-reference/protocols/esp_serial_slave_link` 和示例 :example:`peripherals/sdio/host`。
|
||||
|
||||
复合卡（存储 + IO）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
复合卡（存储 + IO）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
该驱动程序不支持 SD 复合卡，复合卡会被视为 IO 卡。
|
||||
该驱动程序不支持 SD 复合卡，复合卡会被视为 IO 卡。
|
||||
|
||||
|
||||
线程安全
|
||||
|
||||
Loading…
Reference in New Issue
Block a user