mirror of
https://github.com/espressif/esp-idf.git
synced 2026-05-04 20:05:25 +02:00
essl: new component to communicate with esp serial slave devices
This commit is contained in:
Michael (XIAO Xufeng)
@@ -76,7 +76,10 @@ ESP SDIO slave protocol
|
||||
-----------------------
|
||||
|
||||
The protocol is based on Function 1 access by CMD52 and CMD53, offering 3 services: (1) sending and receiving FIFO, (2) 52 8-bit R/W
|
||||
register shared by host and slave, (3) 8 general purpose interrupt sources from host to slave and 8 in the oppsite direction.
|
||||
register shared by host and slave, (3) 8 general purpose interrupt sources from host to slave and 8 in the opposite direction.
|
||||
|
||||
There is a component `esp_serial_slave_link` implementing the logic of this protocol for
|
||||
ESP32 master to communicate with the ESP32 slave. See :doc:`/api-reference/protocols/esp_serial_slave_link`.
|
||||
|
||||
The host should access the registers below as described to communicate with slave.
|
||||
|
||||
@@ -154,7 +157,7 @@ To write the receiving FIFO in the slave, host should work in the following step
|
||||
|
||||
1. Read the TOKEN1 field (bits 27-16) of TOKEN_RDATA (0x044) register. The buffer number remaining is TOKEN1 minus
|
||||
the number of buffers used by host.
|
||||
2. Make sure the buffer number is sufficient (*buffer_size* * *buffer_num* is greater than data to write, *buffer_size*
|
||||
2. Make sure the buffer number is sufficient (*recv_buffer_size* * *buffer_num* is greater than data to write, *recv_buffer_size*
|
||||
is pre-defined between the host and the slave before the communication starts). Or go back to step 1 until the buffer
|
||||
is enough.
|
||||
3. Write to the FIFO address with CMD53. Note that the *requested length* should not be larger than calculated in step 2,
|
||||
|
||||
@@ -127,9 +127,11 @@ SDIO initialization process (Sector 3.1.2 of `SDIO Simplified
|
||||
Specification <https://www.sdcard.org/downloads/pls/>`_), which is described
|
||||
briefly in :ref:`esp_slave_init`.
|
||||
|
||||
Furthermore, there's an ESP32-specific upper-level communication protocol upon
|
||||
the CMD52/CMD53 to Func 1. Please refer to :ref:`esp_slave_protocol_layer`,
|
||||
or example :example:`peripherals/sdio` when programming your host.
|
||||
Furthermore, there's an ESP32-specific upper-level communication protocol upon the CMD52/CMD53 to
|
||||
Func 1. Please refer to :ref:`esp_slave_protocol_layer`. There is also a component
|
||||
:doc:`ESP Serial Slave Link </api-reference/protocols/esp_serial_slave_link>`
|
||||
for ESP32 master to communicate with ESP32 SDIO slave, see example :example:`peripherals/sdio`
|
||||
when programming your host.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
ESP Serial Slave Link
|
||||
=====================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Espressif provides several chips that can work as slaves. These slave devices rely on some
|
||||
common buses, and have their own communication protocols over those buses. The `esp_serial_slave_link` component is
|
||||
designed for the master to communicate with ESP slave devices through those protocols over the
|
||||
bus drivers.
|
||||
|
||||
After an `esp_serial_slave_link` device is initialized properly, the application can use it to communicate with the ESP
|
||||
slave devices conveniently.
|
||||
|
||||
For more details about ESP32 SDIO slave protocol, see document :doc:`/api-reference/peripherals/esp_slave_protocol`.
|
||||
|
||||
Terminology
|
||||
-----------
|
||||
|
||||
- ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document.
|
||||
|
||||
- Master: The device running the `esp_serial_slave_link` component.
|
||||
|
||||
- ESSL device: a virtual device on the master associated with an ESP slave device. The device
|
||||
context has the knowledge of the slave protocol above the bus, relying on some bus drivers to
|
||||
communicate with the slave.
|
||||
|
||||
- ESSL device handle: a handle to ESSL device context containing the configuration, status and
|
||||
data required by the ESSL component. The context stores the driver configurations,
|
||||
communication state, data shared by master and slave, etc.
|
||||
|
||||
The context should be initialized before it is used, and get deinitialized if not used any more. The
|
||||
master application operates on the ESSL device through this handle.
|
||||
|
||||
- ESP slave: the slave device connected to the bus, which ESSL component is designed to
|
||||
communicate with.
|
||||
|
||||
- Bus: The bus over which the master and the slave communicate with each other.
|
||||
|
||||
- Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus.
|
||||
|
||||
- TX buffer num: a counter, which is on the slave and can be read by the master, indicates the
|
||||
accumulated buffer numbers that the slave has loaded to the hardware to receive data from the
|
||||
master.
|
||||
|
||||
- RX data size: a counter, which is on the slave and can be read by the master, indicates the
|
||||
accumulated data size that the slave has loaded to the hardware to send to the master.
|
||||
|
||||
Services provided by ESP slave
|
||||
------------------------------
|
||||
|
||||
There are some common services provided by the Espressif slaves:
|
||||
|
||||
1. Tohost Interrupts: The slave can inform the master about certain events by the interrupt line.
|
||||
|
||||
2. Frhost Interrupts: The master can inform the slave about certain events.
|
||||
|
||||
3. Tx FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can
|
||||
also indicate it has new data to send to master by the interrupt line.
|
||||
|
||||
The slave updates the TX buffer num to inform the master how much data it can receive, and the
|
||||
master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining.
|
||||
|
||||
4. Rx FIFO (slave to master): the slave can receive data from the master in units of receiving
|
||||
buffers.
|
||||
|
||||
The slave updates the RX data size to inform the master how much data it has prepared to
|
||||
send, and then the master read the data size, and take off the data length it has already received to know how many
|
||||
data is remaining.
|
||||
|
||||
5. Shared registers: the master can read some part of the registers on the slave, and also write
|
||||
these registers to let the slave read.
|
||||
|
||||
|
||||
Initialization of ESP SDIO Slave Link
|
||||
-------------------------------------
|
||||
|
||||
The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. The ESSL device should
|
||||
be initialized as below:
|
||||
|
||||
1. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`)
|
||||
structure.
|
||||
|
||||
2. Call :cpp:func:`sdmmc_card_init` to initialize the card.
|
||||
|
||||
3. Initialize the ESSL device with :cpp:type:`essl_sdio_config_t`. The `card` member should be
|
||||
the :cpp:type:`sdmmc_card_t` got in step 2, and the `recv_buffer_size` member should be filled
|
||||
correctly according to pre-negotiated value.
|
||||
|
||||
4. Call :cpp:func:`essl_init` to do initialization of the SDIO part.
|
||||
|
||||
5. Call :cpp:func:`essl_wait_for_ready` to wait for the slave to be ready.
|
||||
|
||||
APIs
|
||||
----
|
||||
|
||||
After the initialization process above is performed, you can call the APIs below to make use of
|
||||
the services provided by the slave:
|
||||
|
||||
Interrupts
|
||||
^^^^^^^^^^
|
||||
|
||||
1. Call :cpp:func:`essl_get_intr_ena` to know which events will trigger the interrupts to the master.
|
||||
|
||||
2. Call :cpp:func:`essl_set_intr_ena` to set the events that will trigger interrupts to the master.
|
||||
|
||||
3. Call :cpp:func:`essl_wait_int` to wait until interrupt from the slave, or timeout.
|
||||
|
||||
4. When interrupt is triggered, call :cpp:func:`essl_get_intr` to know which events are active,
|
||||
and call :cpp:func:`essl_clear_intr` to clear them.
|
||||
|
||||
5. Call :cpp:func:`essl_send_slave_intr` to trigger general purpose interrupt of the slave.
|
||||
|
||||
TX FIFO
|
||||
^^^^^^^
|
||||
|
||||
1. Call :cpp:func:`essl_get_tx_buffer_num` to know how many buffers the slave has prepared to
|
||||
receive data from the master. This is optional. The master will poll `tx_buffer_num` when it try
|
||||
to send packets to the slave, until the slave has enough buffer or timeout.
|
||||
|
||||
2. Call :cpp:func:`essl_send_paket` to send data to the slave.
|
||||
|
||||
RX FIFO
|
||||
^^^^^^^
|
||||
|
||||
1. Call :cpp:func:`essl_get_rx_data_size` to know how many data the slave has prepared to send to
|
||||
the master. This is optional. When the master tries to receive data from the slave, it will update
|
||||
the `rx_data_size` for once, if the current `rx_data_size` is shorter than the buffer size the
|
||||
master prepared to receive. And it may poll the `rx_data_size` if the `rx_dat_size` keeps 0,
|
||||
until timeout.
|
||||
|
||||
2. Call :cpp:func:`essl_get_packet` to receive data from the slave.
|
||||
|
||||
Reset counters (Optional)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Call :cpp:func:`essl_reset_cnt` to reset the internal counter if you find the slave has reset its
|
||||
counter.
|
||||
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
The example below shows how ESP32 SDIO host and slave communicate with each other. The host use the ESSL SDIO.
|
||||
|
||||
:example:`peripherals/sdio`.
|
||||
|
||||
Please refer to the specific example README.md for details.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/essl.inc
|
||||
.. include:: /_build/inc/essl_sdio.inc
|
||||
@@ -16,6 +16,7 @@ Application Protocols
|
||||
mDNS <mdns>
|
||||
Modbus <modbus>
|
||||
Websocket Client <esp_websocket_client>
|
||||
ESP Serial Slave Link <esp_serial_slave_link>
|
||||
|
||||
Code examples for this API section are provided in the :example:`protocols` directory of ESP-IDF examples.
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ In particular, the driver does not set any bits in (1) I/O Enable and Int Enable
|
||||
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
|
||||
|
||||
========================================================================= ================================= =================================
|
||||
Action Read Function Write Function
|
||||
Action Read Function Write Function
|
||||
========================================================================= ================================= =================================
|
||||
Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte`
|
||||
Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes`
|
||||
@@ -82,6 +82,8 @@ SDIO interrupts can be enabled by the application using the function :cpp:func:`
|
||||
|
||||
If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`.
|
||||
|
||||
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32
|
||||
SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
|
||||
|
||||
Combo (memory + IO) cards
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Reference in New Issue
Block a user