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 .. 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