e148c2a12c
- Split SDMMC page into pages about SDMMC/SDSPI hosts and a page about the protocol layer. - Use autogenerated API reference instead of manually generated one. - Add information about SDIO APIs.
78 lines
4.7 KiB
ReStructuredText
78 lines
4.7 KiB
ReStructuredText
SD/SDIO/MMC Driver
|
|
==================
|
|
|
|
Overview
|
|
--------
|
|
|
|
SD/SDIO/MMC driver currently supports SD memory and IO cards. Support for MCC/eMMC cards will be added in the future. This protocol level driver builds on top of SDMMC and SD SPI host drivers.
|
|
|
|
SDMMC and SD SPI host drivers (``driver/sdmmc_host.h``) provide APIs to send commands to the slave device(s), send and receive data, and handle error conditions on the bus.
|
|
|
|
- See :doc:`SDMMC Host API <../peripherals/sdmmc_host>` for functions used to initialize and configure SDMMC host.
|
|
- See :doc:`SD SPI Host API <../peripherals/sdspi_host>` for functions used to initialize and configure SD SPI host.
|
|
|
|
SDMMC protocol layer (``sdmmc_cmd.h``), described in this document, handles specifics of SD protocol such as card initialization and data transfer commands.
|
|
|
|
Protocol layer works with the host via :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host.
|
|
|
|
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 :cpp:class:`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 :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, protocol layer uses :cpp:class:`sdmmc_command_t` structure to describe the command, argument, expected return value, and data to transfer, if any.
|
|
|
|
Usage with SD memory cards
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
1. Call the host driver functions to initialize the host (e.g. :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`).
|
|
2. Call :cpp:func:`sdmmc_card_init` to initialize the card, passing it host driver information (``host``) and a pointer to :cpp:class:`sdmmc_card_t` structure which will be filled in (``card``).
|
|
3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`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 the host peripheral and free resources allocated by the driver (e.g. :cpp:func:`sdmmc_host_deinit`).
|
|
|
|
Usage with SDIO cards
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Initialization an probing process is the same as with SD memory cards. Only data transfer commands differ in SDIO mode.
|
|
|
|
During probing and card initialization (done by :cpp:func:`sdmmc_card_init`), the driver only configures the following registers of the IO card:
|
|
|
|
1. The IO portion of the card is reset by setting RES bit in "I/O Abort" (0x06) register.
|
|
2. If 4-line mode is enalbed in host and slot configuration, driver attempts to set "Bus width" field in "Bus Interface Control" (0x07) register. If that succeeds (which means that slave supports 4-line mode), host is also switched to 4-line mode.
|
|
3. If high-speed mode is enabled in host configuration, SHS bit is set in "High Speed" (0x13) register.
|
|
|
|
In particular, the driver does not set any of the bits in I/O Enable, Int Enable registers, IO block sizes, etc. Applications can set these by calling :cpp:func:`sdmmc_io_write_byte`.
|
|
|
|
For card configuration and data transfer, use one of the following functions:
|
|
|
|
- :cpp:func:`sdmmc_io_read_byte`, :cpp:func:`sdmmc_io_write_byte` — read and write single byte using IO_RW_DIRECT (CMD52).
|
|
- :cpp:func:`sdmmc_io_read_bytes`, :cpp:func:`sdmmc_io_write_bytes` — read and write multiple bytes using IO_RW_EXTENDED (CMD53), in byte mode.
|
|
- :cpp:func:`sdmmc_io_read_blocks`, :cpp:func:`sdmmc_io_write_blocks` — read and write blocks of data using IO_RW_EXTENDED (CMD53), in block mode.
|
|
|
|
SDIO interrupts can be enabled by the application using :cpp:func:`sdmmc_io_enable_int` function. When using SDIO in 1-line mode, D1 line also needs to be connected to use SDIO interrupts.
|
|
|
|
The application can wait for SDIO interrupt to occur using :cpp:func:`sdmmc_io_wait_int`.
|
|
|
|
Combo (memory + IO) cards
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The driver does not support SD combo cards. Combo cards will be treated as IO cards.
|
|
|
|
|
|
Thread safety
|
|
^^^^^^^^^^^^^
|
|
|
|
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 :cpp:class:`sdmmc_card_t` structure, or when accessing SDMMC or SD SPI host drivers. Such locking is usually implemented in the higher layer (e.g. in the filesystem driver).
|
|
|
|
|
|
API Reference
|
|
-------------
|
|
|
|
.. include:: /_build/inc/sdmmc_cmd.inc
|
|
|
|
.. include:: /_build/inc/sdmmc_types.inc
|