96 lines
4.7 KiB
ReStructuredText
96 lines
4.7 KiB
ReStructuredText
SDMMC Host Peripheral
|
|
=====================
|
|
|
|
Overview
|
|
--------
|
|
|
|
SDMMC peripheral supports SD and MMC memory cards and SDIO cards. SDMMC software builds on top of SDMMC driver and consists of the following parts:
|
|
|
|
1. SDMMC host driver (``driver/sdmmc_host.h``) — this driver provides APIs to send commands to the slave device(s), send and receive data, and handling error conditions on the bus.
|
|
|
|
2. SDMMC protocol layer (``sdmmc_cmd.h``) — this component handles specifics of SD protocol such as card initialization and data transfer commands. Despite the name, only SD (SDSC/SDHC/SDXC) cards are supported at the moment. Support for MCC/eMMC cards can be added in the future.
|
|
|
|
Protocol layer works with the host via ``sdmmc_host_t`` structure. This structure contains pointers to various functions of the host. This design makes it possible to implement an SD host using SPI interface later.
|
|
|
|
Application Example
|
|
-------------------
|
|
|
|
An example which combines SDMMC driver with FATFS library is provided in ``examples/storage/sd_card`` directory. This example initializes the card, 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 APIs
|
|
-------------------
|
|
|
|
Protocol layer is given ``sdmmc_host_t`` structure which describes the SD/MMC host driver, lists its capabilites, and provides pointers to functions of the driver. Protocol layer stores card-specific information in ``sdmmc_card_t`` structure. When sending commands to the SD/MMC host driver, protocol layer uses ``sdmmc_command_t`` structure to describe the command, argument, expected return value, and data to transfer, if any.
|
|
|
|
Normal usage of the protocol layer is as follows:
|
|
|
|
1. Call the host driver functions to initialize the host (e.g. ``sdmmc_host_init``, ``sdmmc_host_init_slot``).
|
|
2. Call ``sdmmc_card_init`` to initialize the card, passing it host driver information (``host``) and a pointer to ``sdmmc_card_t`` structure which will be filled in (``card``).
|
|
3. To read and write sectors of the card, use ``sdmmc_read_sectors`` and ``sdmmc_write_sectors``, passing the pointer to card information structure (``card``).
|
|
4. When card is not used anymore, call the host driver function to disable SDMMC host peripheral and free resources allocated by the driver (e.g. ``sdmmc_host_deinit``).
|
|
|
|
Most applications need to use the protocol layer only in one task; therefore the protocol layer doesn't implement any kind of locking on the ``sdmmc_card_t`` structure, or when accessing SDMMC host driver. Such locking has to be implemented in the higher layer, if necessary (e.g. in the filesystem driver).
|
|
|
|
.. doxygenstruct:: sdmmc_host_t
|
|
:members:
|
|
|
|
.. doxygendefine:: SDMMC_HOST_FLAG_1BIT
|
|
.. doxygendefine:: SDMMC_HOST_FLAG_4BIT
|
|
.. doxygendefine:: SDMMC_HOST_FLAG_8BIT
|
|
.. doxygendefine:: SDMMC_HOST_FLAG_SPI
|
|
.. doxygendefine:: SDMMC_FREQ_DEFAULT
|
|
.. doxygendefine:: SDMMC_FREQ_HIGHSPEED
|
|
.. doxygendefine:: SDMMC_FREQ_PROBING
|
|
|
|
.. doxygenstruct:: sdmmc_command_t
|
|
:members:
|
|
|
|
.. doxygenstruct:: sdmmc_card_t
|
|
:members:
|
|
|
|
.. doxygenstruct:: sdmmc_csd_t
|
|
:members:
|
|
|
|
.. doxygenstruct:: sdmmc_cid_t
|
|
:members:
|
|
|
|
.. doxygenstruct:: sdmmc_scr_t
|
|
:members:
|
|
|
|
.. doxygenfunction:: sdmmc_card_init
|
|
.. doxygenfunction:: sdmmc_write_sectors
|
|
.. doxygenfunction:: sdmmc_read_sectors
|
|
|
|
SDMMC host driver APIs
|
|
----------------------
|
|
|
|
On the ESP32, SDMMC host peripheral has two slots:
|
|
|
|
- Slot 0 (``SDMMC_HOST_SLOT_0``) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
|
|
- Slot 1 (``SDMMC_HOST_SLOT_1``) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
|
|
|
|
Card Detect and Write Protect signals can be routed to arbitrary pins using GPIO matrix. To use these pins, set ``gpio_cd`` and ``gpio_wp`` members of ``sdmmc_slot_config_t`` structure when calling ``sdmmc_host_init_slot``.
|
|
|
|
Of all the funtions listed below, only ``sdmmc_host_init``, ``sdmmc_host_init_slot``, and ``sdmmc_host_deinit`` will be used directly by most applications. Other functions, such as ``sdmmc_host_set_bus_width``, ``sdmmc_host_set_card_clk``, and ``sdmmc_host_do_transaction`` will be called by the SD/MMC protocol layer via function pointers in ``sdmmc_host_t`` structure.
|
|
|
|
.. doxygenfunction:: sdmmc_host_init
|
|
|
|
.. doxygendefine:: SDMMC_HOST_SLOT_0
|
|
.. doxygendefine:: SDMMC_HOST_SLOT_1
|
|
.. doxygendefine:: SDMMC_HOST_DEFAULT
|
|
.. doxygendefine:: SDMMC_SLOT_WIDTH_DEFAULT
|
|
|
|
.. doxygenfunction:: sdmmc_host_init_slot
|
|
|
|
.. doxygenstruct:: sdmmc_slot_config_t
|
|
:members:
|
|
|
|
.. doxygendefine:: SDMMC_SLOT_NO_CD
|
|
.. doxygendefine:: SDMMC_SLOT_NO_WP
|
|
.. doxygendefine:: SDMMC_SLOT_CONFIG_DEFAULT
|
|
|
|
.. doxygenfunction:: sdmmc_host_set_bus_width
|
|
.. doxygenfunction:: sdmmc_host_set_card_clk
|
|
.. doxygenfunction:: sdmmc_host_do_transaction
|
|
.. doxygenfunction:: sdmmc_host_deinit
|