1ESP Serial Slave Link
2=====================
3
4Overview
5--------
6
7Espressif provides several chips that can work as slaves. These slave devices rely on some
8common buses, and have their own communication protocols over those buses. The `esp_serial_slave_link` component is
9designed for the master to communicate with ESP slave devices through those protocols over the
10bus drivers.
11
12After an `esp_serial_slave_link` device is initialized properly, the application can use it to communicate with the ESP
13slave devices conveniently.
14
15Espressif Device protocols
16--------------------------
17
18For more details about Espressif device protocols, see the following documents.
19
20.. toctree::
21    :maxdepth: 1
22
23    :SOC_SDIO_SLAVE_SUPPORTED: esp_sdio_slave_protocol
24    esp_spi_slave_protocol
25
26Terminology
27-----------
28
29- ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document.
30
31- Master: The device running the `esp_serial_slave_link` component.
32
33- ESSL device: a virtual device on the master associated with an ESP slave device. The device
34  context has the knowledge of the slave protocol above the bus, relying on some bus drivers to
35  communicate with the slave.
36
37- ESSL device handle: a handle to ESSL device context containing the configuration, status and
38  data required by the ESSL component. The context stores the driver configurations,
39  communication state, data shared by master and slave, etc.
40
41  The context should be initialized before it is used, and get deinitialized if not used any more. The
42  master application operates on the ESSL device through this handle.
43
44- ESP slave: the slave device connected to the bus, which ESSL component is designed to
45  communicate with.
46
47- Bus: The bus over which the master and the slave communicate with each other.
48
49- Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus.
50
51- TX buffer num: a counter, which is on the slave and can be read by the master, indicates the
52  accumulated buffer numbers that the slave has loaded to the hardware to receive data from the
53  master.
54
55- RX data size: a counter, which is on the slave and can be read by the master, indicates the
56  accumulated data size that the slave has loaded to the hardware to send to the master.
57
58Services provided by ESP slave
59------------------------------
60
61There are some common services provided by the Espressif slaves:
62
631. Tohost Interrupts: The slave can inform the master about certain events by the interrupt line. (optional)
64
652. Frhost Interrupts: The master can inform the slave about certain events.
66
673. Tx FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can
68   also indicate it has new data to send to master by the interrupt line.
69
70   The slave updates the TX buffer num to inform the master how much data it can receive, and the
71   master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining.
72
734. Rx FIFO (slave to master): the slave can receive data from the master in units of receiving
74   buffers.
75
76   The slave updates the RX data size to inform the master how much data it has prepared to
77   send, and then the master read the data size, and take off the data length it has already received to know how many
78   data is remaining.
79
805. Shared registers: the master can read some part of the registers on the slave, and also write
81   these registers to let the slave read.
82
83.. only:: SOC_SDIO_SLAVE_SUPPORTED
84
85   The services provided by the slave depends on the slave's model. See :ref:`esp_sdio_slave_caps` and :ref:`esp_spi_slave_caps` for more details.
86
87.. only:: not SOC_SDIO_SLAVE_SUPPORTED
88
89   The services provided by the slave depends on the slave's model. See :ref:`esp_spi_slave_caps` for more details.
90
91
92Initialization of ESP Serial Slave Link
93---------------------------------------
94
95.. _essl_sdio_slave_init:
96
97ESP SDIO Slave
98^^^^^^^^^^^^^^
99
100The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. It includes the usage
101of communicating with ESP SDIO Slave device via SDSPI feature. The ESSL device should be
102initialized as below:
103
1041. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`)
105   structure.
106
1072. Call :cpp:func:`sdmmc_card_init` to initialize the card.
108
1093. Initialize the ESSL device with :cpp:type:`essl_sdio_config_t`. The `card` member should be
110   the :cpp:type:`sdmmc_card_t` got in step 2, and the `recv_buffer_size` member should be filled
111   correctly according to pre-negotiated value.
112
1134. Call :cpp:func:`essl_init` to do initialization of the SDIO part.
114
1155. Call :cpp:func:`essl_wait_for_ready` to wait for the slave to be ready.
116
117ESP SPI Slave
118^^^^^^^^^^^^^
119
120.. note::
121    If you are communicating with the ESP SDIO Slave device through SPI interface, you should use
122    the :ref:`SDIO interface <essl_sdio_slave_init>` instead.
123
124Hasn't been supported yet.
125
126APIs
127----
128
129After the initialization process above is performed, you can call the APIs below to make use of
130the services provided by the slave:
131
132Tohost Interrupts (optional)
133^^^^^^^^^^^^^^^^^^^^^^^^^^^^
134
1351. Call :cpp:func:`essl_get_intr_ena` to know which events will trigger the interrupts to the master.
136
1372. Call :cpp:func:`essl_set_intr_ena` to set the events that will trigger interrupts to the master.
138
1393. Call :cpp:func:`essl_wait_int` to wait until interrupt from the slave, or timeout.
140
1414. When interrupt is triggered, call :cpp:func:`essl_get_intr` to know which events are active,
142   and call :cpp:func:`essl_clear_intr` to clear them.
143
144Frhost Interrupts
145^^^^^^^^^^^^^^^^^
146
1471. Call :cpp:func:`essl_send_slave_intr` to trigger general purpose interrupt of the slave.
148
149TX FIFO
150^^^^^^^
151
1521. Call :cpp:func:`essl_get_tx_buffer_num` to know how many buffers the slave has prepared to
153   receive data from the master. This is optional. The master will poll `tx_buffer_num` when it try
154   to send packets to the slave, until the slave has enough buffer or timeout.
155
1562. Call :cpp:func:`essl_send_paket` to send data to the slave.
157
158RX FIFO
159^^^^^^^
160
1611. Call :cpp:func:`essl_get_rx_data_size` to know how many data the slave has prepared to send to
162   the master. This is optional. When the master tries to receive data from the slave, it will update
163   the `rx_data_size` for once, if the current `rx_data_size` is shorter than the buffer size the
164   master prepared to receive. And it may poll the `rx_data_size` if the `rx_dat_size` keeps 0,
165   until timeout.
166
1672. Call :cpp:func:`essl_get_packet` to receive data from the slave.
168
169Reset counters (Optional)
170^^^^^^^^^^^^^^^^^^^^^^^^^
171
172Call :cpp:func:`essl_reset_cnt` to reset the internal counter if you find the slave has reset its
173counter.
174
175
176Application Example
177-------------------
178
179The example below shows how {IDF_TARGET_NAME} SDIO host and slave communicate with each other. The host use the ESSL SDIO.
180
181:example:`peripherals/sdio`.
182
183Please refer to the specific example README.md for details.
184
185API Reference
186-------------
187
188.. include-build-file:: inc/essl.inc
189.. include-build-file:: inc/essl_sdio.inc
190.. include-build-file:: inc/essl_spi.inc
191