docs: update SDMMC and SDSPI documentation

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

docs/en/api-reference/peripherals/index.rst

@@ -13,7 +13,8 @@ Peripherals API
    MCPWM <mcpwm>
    Pulse Counter <pcnt>
    Remote Control <rmt>
-   SD/MMC Card Host <../storage/sdmmc>
+   SDMMC Host <sdmmc_host>
+   SD SPI Host <sdspi_host>
    Sigma-delta Modulation <sigmadelta>
    SPI Master <spi_master>
    SPI Slave <spi_slave>

docs/en/api-reference/peripherals/sdmmc_host.rst

@@ -0,0 +1,66 @@
+SDMMC Host Driver
+=================
+
+Overview
+--------
+
+On the ESP32, SDMMC host peripheral has two slots:
+
+- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX.
+- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX.
+
+Pin mappings of these slots are given in the following table:
+
+    +--------+-------------+-------------+
+    | Signal | Slot 0      | Slot 1      |
+    +========+=============+=============+
+    | CMD    | GPIO11      | GPIO15      |
+    +--------+-------------+-------------+
+    | CLK    | GPIO6       | GPIO14      |
+    +--------+-------------+-------------+
+    | D0     | GPIO7       | GPIO2       |
+    +--------+-------------+-------------+
+    | D1     | GPIO8       | GPIO4       |
+    +--------+-------------+-------------+
+    | D2     | GPIO9       | GPIO12      |
+    +--------+-------------+-------------+
+    | D3     | GPIO10      | GPIO13      |
+    +--------+-------------+-------------+
+    | D4     | GPIO16      |             |
+    +--------+-------------+-------------+
+    | D5     | GPIO17      |             |
+    +--------+-------------+-------------+
+    | D6     | GPIO5       |             |
+    +--------+-------------+-------------+
+    | D7     | GPIO18      |             |
+    +--------+-------------+-------------+
+    | CD     | any input via GPIO matrix |
+    +--------+---------------------------+
+    | WP     | any input via GPIO matrix |
+    +--------+---------------------------+
+
+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 :cpp:class:`sdmmc_slot_config_t` structure when calling :cpp:func:`sdmmc_host_init_slot`. Note that it is not advised to specify Card Detect pin when working with SDIO cards, because in ESP32 card detect signal can also trigger SDIO slave interrupt.
+
+.. warning::
+    
+    Pins used by slot 0 (``HS1_*``) are also used to connect SPI flash chip in ESP-WROOM32 and ESP32-WROVER modules. These pins can not be shared between SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set Efuses accordingly.
+
+
+Using the SDMMC Host driver
+---------------------------
+
+Of all the funtions listed below, only :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`, and :cpp:func:`sdmmc_host_deinit` will be used directly by most applications.
+
+Other functions, such as :cpp:func:`sdmmc_host_set_bus_width`, :cpp:func:`sdmmc_host_set_card_clk`, and :cpp:func:`sdmmc_host_do_transaction` will be called by the SD/MMC protocol layer via function pointers in :cpp:class:`sdmmc_host_t` structure.
+
+See also
+--------
+
+See :doc:`SD/SDIO/MMC Driver <../storage/sdmmc>` for the higher level driver which implements the protocol layer.
+
+See :doc:`SD SPI Host Driver <sdspi_host>` for a similar driver which uses SPI controller and is limited to SPI mode of SD protocol.
+
+API Reference
+-------------
+
+.. include:: /_build/inc/sdmmc_host.inc

docs/en/api-reference/peripherals/sdspi_host.rst

@@ -0,0 +1,25 @@
+SD SPI Host Driver
+==================
+
+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.
+
+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. 
+
+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.
+
+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.
+
+.. note:
+	
+	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.
+
+
+API Reference
+-------------
+
+.. include:: /_build/inc/sdspi_host.inc