1Communication with ESP SDIO Slave 2================================= 3 4This document describes the process of initialization of an ESP SDIO Slave device and then provides details on the ESP SDIO Slave protocol - a non-standard protocol that allows an SDIO Host to communicate with an ESP SDIO slave. 5 6The ESP SDIO Slave protocol was created to implement the communication between SDIO host and slave, because the SDIO specification only shows how to access the custom region of a card (by sending CMD52 and CMD53 to Functions 1-7) without any details regarding the underlying hardware implementation. 7 8.. _esp_sdio_slave_caps: 9 10SDIO Slave Capabilities of Espressif chips 11------------------------------------------ 12 13The services provided by the SDIO Slave peripheral of the {IDF_TARGET_NAME} chip are listed in the table below: 14 15.. list-table:: 16 :widths: 70 30 17 :header-rows: 1 18 19 * - Services 20 - {IDF_TARGET_NAME} 21 * - SDIO slave 22 - Y 23 * - :ref:`Tohost intr <esp_sdio_slave_interrupts>` 24 - 8 25 * - :ref:`Frhost intr <esp_sdio_slave_interrupts>` 26 - 8 27 * - :ref:`TX DMA <esp_sdio_slave_send_fifo>` 28 - Y 29 * - :ref:`RX DMA <esp_sdio_slave_rcv_fifo>` 30 - Y 31 * - :ref:`Shared registers <esp_sdio_slave_shared_registers>` 32 - 56\* 33 34- \* Not including the interrupt registers 35 36 37.. _esp_slave_init: 38 39ESP SDIO Slave Initialization 40----------------------------- 41 42The host should initialize the ESP32 SDIO slave according to the standard SDIO initialization process (Section 3.1.2 of `SDIO Simplified Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification as well as below, the SDIO slave is called an (SD)IO card. Here is a brief example of an ESP SDIO Slave initialization process: 43 441. SDIO reset 45 CMD52 (Write 0x6=0x8) 46 472. SD reset 48 CMD0 49 503. Check whether IO card (optional) 51 CMD8 52 534. Send SDIO op cond and wait for card ready 54 CMD5 arg = 0x00000000 55 56 CMD5 arg = 0x00ff8000 (according to the response above, poll until ready) 57 58 **Example:** 59 Arg of R4 after first CMD5 (arg=0x00000000) is 0xXXFFFF00. 60 61 Keep sending CMD5 with arg=0x00FFFF00 until the R4 shows card ready (arg bit 31=1). 62 635. Set address 64 CMD3 65 666. Select card 67 CMD7 (arg address according to CMD3 response) 68 69 **Example:** 70 Arg of R6 after CMD3 is 0x0001xxxx. 71 72 Arg of CMD7 should be 0x00010000. 73 747. Select 4-bit mode (optional) 75 CMD52 (Write 0x07=0x02) 76 778. Enable func1 78 CMD52 (Write 0x02=0x02) 79 809. Enable SDIO interrupt (required if interrupt line (DAT1) is used) 81 CMD52 (Write 0x04=0x03) 82 8310. Set Func0 blocksize (optional, default value is 512 (0x200)) 84 CMD52/53 (Read 0x10~0x11) 85 86 CMD52/53 (Write 0x10=0x00) 87 88 CMD52/53 (Write 0x11=0x02) 89 90 CMD52/53 (Read 0x10~0x11, read to check the final value) 91 9211. Set Func1 blocksize (optional, default value is 512 (0x200)) 93 CMD52/53 (Read 0x110~0x111) 94 95 CMD52/53 (Write 0x110=0x00) 96 97 CMD52/53 (Write 0x111=0x02) 98 99 CMD52/53 (Read 0x110~0x111, read to check the final value) 100 101 102.. _esp_slave_protocol_layer: 103 104ESP SDIO Slave Protocol 105----------------------- 106 107The ESP SDIO Slave protocol is based on the SDIO Specification's I/O Read/Write commands, i.e., CMD52 and CMD53. The protocol offers the following services: 108 109- Sending FIFO and receiving FIFO 110- 52 8-bit R/W registers shared by host and slave (For details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *SDIO Slave Controller* > *Register Summary* > SDIO SLC Host registers [`PDF <{IDF_TARGET_TRM_EN_URL}#sdioslave-reg-summ>`__] 111- 16 general purpose interrupt sources, 8 from host to slave and 8 from slave to host 112 113To begin communication, the host needs to enable the I/O Function 1 in the slave and access its registers as described below. 114 115Check the code example :example:`peripherals/sdio`. 116 117The :doc:`ESP Serial Slave Link </api-reference/protocols/esp_serial_slave_link>` component implements the logic of this protocol for ESP32 SDIO Host when communicating with an ESP32 SDIO slave. 118 119.. _esp_sdio_slave_shared_registers: 120 121Slave register table 122^^^^^^^^^^^^^^^^^^^^ 123 12432-bit 125"""""" 126 127- 0x044 (TOKEN_RDATA): in which bit 27-16 holds the number of the receiving buffer. 128- 0x058 (INT_ST): holds the interrupt source bits from slave to host. 129- 0x060 (PKT_LEN): holds the accumulated data length (in bytes) already read by host plus the data copied to the buffer but yet to be read. 130- 0x0D4 (INT_CLR): write 1 to clear interrupt bits corresponding to INT_ST. 131- 0x0DC (INT_ENA): mask bits for interrupts from slave to host. 132 1338-bit 134""""" 135 136Shared general purpose registers: 137 138- 0x06C-0x077: R/W registers 0-11 shared by slave and host. 139- 0x07A-0x07B: R/W registers 14-15 shared by slave and host. 140- 0x07E-0x07F: R/W registers 18-19 shared by slave and host. 141- 0x088-0x08B: R/W registers 24-27 shared by slave and host. 142- 0x09C-0x0BB: R/W registers 32-63 shared by slave and host. 143 144Interrupt Registers: 145- 0x08D (SLAVE_INT): bits for host to interrupt slave. auto clear. 146 147FIFO (sending and receiving) 148"""""""""""""""""""""""""""" 149 1500x090 - 0x1F7FF are reserved for FIFOs. 151 152The address of CMD53 is related to the length requested to read from or write to the slave in a single transfer, as demonstrated by the equation below: 153 154 *requested length = 0x1F800-address* 155 156The slave will respond with data that has a length equal to the length field of CMD53. In cases where the data is longer than the *requested length*, the data will be zero filled (when sending) or discarded (when receiving). This includes both the block and the byte mode of CMD53. 157 158.. note:: 159 160 The function number should be set to 1, OP Code should be set to 1 (for CMD53). 161 162 In order to achieve higher efficiency when accessing the FIFO by an arbitrary length, the block and byte modes of CMD53 can be used in combination. For example, given that the block size is set to 512 by default, you can write/get 1031 bytes of data from the FIFO by doing the following: 163 164 1. Send CMD53 in block mode, block count=2 (1024 bytes) to address 0x1F3F9=0x1F800-**1031**. 165 2. Then send CMD53 in byte mode, byte count=8 (or 7 if your controller supports that) to address 0x1F7F9=0x1F800-**7**. 166 167.. _esp_sdio_slave_interrupts: 168 169Interrupts 170^^^^^^^^^^ 171 172SDIO interrupts are "level sensitive". For host interrupts, the slave sends an interrupt by pulling the DAT1 line down at a proper time. The host detects when the interrupt line is pulled down and reads the INT_ST register to determine the source of the interrupt. After that, the host can clear the interrupt bits by writing the INT_CLR register and process the interrupt. The host can also mask unneeded sources by clearing the bits in the INT_ENA register corresponding to the sources. If all the sources are cleared (or masked), the DAT1 line goes inactive. 173 174On ESP32, the corresponding host_int bits are: bit 0 to bit 7. 175 176For slave interrupts, the host sends a transfer to write the SLAVE_INT register. Once a bit is set to 1, the slave hardware and the driver will detect it and inform the application. 177 178.. _esp_sdio_slave_rcv_fifo: 179 180Receiving FIFO 181^^^^^^^^^^^^^^ 182 183To write to the slave's receiving FIFO, the host should complete the following steps: 184 1851. **Read the TOKEN1 field (bits 27-16) of the register TOKEN_RDATA (0x044)**. The buffer number remaining is TOKEN1 minus the number of buffers used by host. 1862. **Make sure the buffer number is sufficient** (*buffer_size* x *buffer_num* is greater than the data to write, *buffer_size* is pre-defined between the host and the slave before the communication starts). Otherwise, keep returning to Step 1 until the buffer size is sufficient. 1873. **Write to the FIFO address with CMD53**. Note that the *requested length* should not exceed the length calculated at Step 2, and the FIFO address is related to *requested length*. 1884. **Calculate used buffers**. Note that a partially used buffer at the tail is counted as used. 189 190.. _esp_sdio_slave_send_fifo: 191 192Sending FIFO 193^^^^^^^^^^^^ 194 195To read the slave's sending FIFO, the host should complete the following steps: 196 1971. **Wait for the interrupt line to become active** (optional, low by default). 1982. **Read (poll) the interrupt bits in the INT_ST register** to monitor if new packets exist. 1993. **If new packets are ready, read the PKT_LEN register**. Before reading the packets, determine the length of data to be read. As the host keeps the length of data already read from the slave, subtract this value from PKT_LEN, the result will be the maximum length of data available for reading. If no data has been added to the sending FIFO yet, wait and poll until the slave is ready and update PKT_LEN. 2004. **Read from the FIFO using CMD53**. Note that the *requested length* should not be greater than calculated at Step 3, and the FIFO address is related to *requested length*. 2015. **Update the read length**. 202 203