Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge branch 'doc/review_api-ref_periph-sdspi_host' into 'master'

Browse source 
Review the file api-reference/peripherals/sdspi_host.rst

See merge request espressif/esp-idf!5732
This commit is contained in:
Krzysztof Budzynski 2019-09-09 19:59:56 +08:00
commit 56231a998b
1 changed files with 33 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
docs/en/api-reference/peripherals/sdspi_host.rst
View file

@ -4,19 +4,44 @@ SD SPI Host Driver
Overview Overview
-------- --------
SPI controllers accessible via spi_master driver (HSPI, VSPI) can be used to work with SD cards. The driver which provides this capability is called "SD SPI Host", due to its similarity with the :doc:`SDMMC Host <sdmmc_host>` driver. The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards. This driver's naming pattern was adopted from the :doc:`SDMMC Host <sdmmc_host>` driver due to their similarity. Likewise, the APIs of both drivers are also very similar.
In SPI mode, SD driver has lower throughput than in 1-line SD mode. However SPI mode makes pin selection more flexible, as SPI peripheral can be connected to any ESP32 pins using GPIO Matrix. SD SPI driver uses software controlled CS signal. Currently SD SPI driver assumes that it can use the SPI controller exclusively, so applications which need to share SPI bus between SD cards and other peripherals need to make sure that SD card and other devices are not used at the same time from different tasks. The SD SPI host driver has the following modes:
SD SPI driver is represented using an :cpp:class:`sdmmc_host_t` structure initialized using :c:macro:`SDSPI_HOST_DEFAULT` macro. For slot initialization, :c:macro:`SDSPI_SLOT_CONFIG_DEFAULT` can be used to fill in default pin mapping, which is the same as the pin mapping in SD mode. - **SPI mode**: offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral's signals can be routed to any ESP32 pin.
- **1-bit SD mode**: offers higher throughput but requires routing the signals through their dedicated IO_MUX pins only.
SD SPI driver APIs are very similar to :doc:`SDMMC host APIs <sdmmc_host>`. As with the SDMMC host driver, only :cpp:func:`sdspi_host_init`, :cpp:func:`sdspi_host_init_slot`, and :cpp:func:`sdspi_host_deinit` functions are normally used by the applications. Other functions are called by the protocol level driver via function pointers in :cpp:class:`sdmmc_host_t` structure. The SD SPI driver uses software-controlled CS signal.
.. note: Currently, the SD SPI driver cannot handle multi-threaded environments as does not support time-division multiplexing on the same SPI bus. It means that if your application needs to communicate with an SD card and other devices on the same SPI bus, the application itself must ensure that its different tasks do not try to access the SPI slaves at the same time.
SD over SPI does not support speeds above SDMMC_FREQ_DEFAULT due to a limitation of SPI driver.
See :doc:`SD/SDIO/MMC Driver <../storage/sdmmc>` for the higher level driver which implements the protocol layer. How to Use
----------
The state and configurations of the SD SPI host driver are stored in a :cpp:type:`sdmmc_host_t` structure. This structure can be initialized using the :c:macro:`SDSPI_HOST_DEFAULT` macro.
The state and configurations of the SD slot are stored in a :cpp:type:`sdmmc_slot_config_t` structure. Use the macro :c:macro:`SDSPI_SLOT_CONFIG_DEFAULT` to initialize the structure and to fill in the default pin mappings (SD mode pin mappings).
Only the following driver's API functions are normally used by most applications:
- :cpp:func:`sdspi_host_init`
- :cpp:func:`sdspi_host_init_slot`
- :cpp:func:`sdspi_host_deinit`
Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the :cpp:type:`sdmmc_host_t` structure. For more details, see :doc:`the SD/SDIO/MMC Driver <../storage/sdmmc>`.
.. note::
SD over SPI does not support speeds above :c:macro:`SDMMC_FREQ_DEFAULT` due to the limitations of the SPI driver.
.. todo
.. The SD SPI API reference could use more detail such as:
.. - Configuration. What are some key points of concern regarding slot configuration.
.. - Which function/how is a transaction done?
.. - Are there code snippets or corresponding application examples?
API Reference API Reference