mirror of
https://github.com/espressif/esp-idf.git
synced 2025-11-26 20:53:11 +00:00
spi_slave_hd: new driver for spi slave in half duplex mode
This commit is contained in:
Michael (XIAO Xufeng)
@@ -1,172 +0,0 @@
|
||||
Communication with ESP SDIO Slave
|
||||
=================================
|
||||
|
||||
This 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.
|
||||
|
||||
The 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.
|
||||
|
||||
|
||||
.. _esp_slave_init:
|
||||
|
||||
ESP SDIO Slave Initialization
|
||||
-----------------------------
|
||||
|
||||
The 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:
|
||||
|
||||
1. SDIO reset
|
||||
CMD52 (Write 0x6=0x8)
|
||||
|
||||
2. SD reset
|
||||
CMD0
|
||||
|
||||
3. Check whether IO card (optional)
|
||||
CMD8
|
||||
|
||||
4. Send SDIO op cond and wait for card ready
|
||||
CMD5 arg = 0x00000000
|
||||
|
||||
CMD5 arg = 0x00ff8000 (according to the response above, poll until ready)
|
||||
|
||||
**Example:**
|
||||
Arg of R4 after first CMD5 (arg=0x00000000) is 0xXXFFFF00.
|
||||
|
||||
Keep sending CMD5 with arg=0x00FFFF00 until the R4 shows card ready (arg bit 31=1).
|
||||
|
||||
5. Set address
|
||||
CMD3
|
||||
|
||||
6. Select card
|
||||
CMD7 (arg address according to CMD3 response)
|
||||
|
||||
**Example:**
|
||||
Arg of R6 after CMD3 is 0x0001xxxx.
|
||||
|
||||
Arg of CMD7 should be 0x00010000.
|
||||
|
||||
7. Select 4-bit mode (optional)
|
||||
CMD52 (Write 0x07=0x02)
|
||||
|
||||
8. Enable func1
|
||||
CMD52 (Write 0x02=0x02)
|
||||
|
||||
9. Enable SDIO interrupt (required if interrupt line (DAT1) is used)
|
||||
CMD52 (Write 0x04=0x03)
|
||||
|
||||
10. Set Func0 blocksize (optional, default value is 512 (0x200))
|
||||
CMD52/53 (Read 0x10~0x11)
|
||||
|
||||
CMD52/53 (Write 0x10=0x00)
|
||||
|
||||
CMD52/53 (Write 0x11=0x02)
|
||||
|
||||
CMD52/53 (Read 0x10~0x11, read to check the final value)
|
||||
|
||||
11. Set Func1 blocksize (optional, default value is 512 (0x200))
|
||||
CMD52/53 (Read 0x110~0x111)
|
||||
|
||||
CMD52/53 (Write 0x110=0x00)
|
||||
|
||||
CMD52/53 (Write 0x111=0x02)
|
||||
|
||||
CMD52/53 (Read 0x110~0x111, read to check the final value)
|
||||
|
||||
|
||||
.. _esp_slave_protocol_layer:
|
||||
|
||||
ESP SDIO Slave Protocol
|
||||
-----------------------
|
||||
|
||||
The 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:
|
||||
|
||||
- Sending FIFO and receiving FIFO
|
||||
- 52 8-bit R/W registers shared by host and slave (For details, see Section 8.4 Register summary (table SDIO SLC Host registers) in `{IDF_TARGET_NAME} Technical reference manual`_
|
||||
- 16 general purpose interrupt sources, 8 from host to slave and 8 from slave to host
|
||||
|
||||
To begin communication, the host needs to enable the I/O Function 1 in the slave and access its registers as described below.
|
||||
|
||||
Check the code example :example:`peripherals/sdio`.
|
||||
|
||||
The :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.
|
||||
|
||||
.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL}
|
||||
|
||||
|
||||
Slave register table
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
32-bit
|
||||
""""""
|
||||
|
||||
- 0x044 (TOKEN_RDATA): in which bit 27-16 holds the number of the receiving buffer.
|
||||
- 0x058 (INT_ST): holds the interrupt source bits from slave to host.
|
||||
- 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.
|
||||
- 0x0D4 (INT_CLR): write 1 to clear interrupt bits corresponding to INT_ST.
|
||||
- 0x0DC (INT_ENA): mask bits for interrupts from slave to host.
|
||||
|
||||
8-bit
|
||||
"""""
|
||||
|
||||
Shared general purpose registers:
|
||||
|
||||
- 0x06C-0x077: R/W registers 0-11 shared by slave and host.
|
||||
- 0x07A-0x07B: R/W registers 14-15 shared by slave and host.
|
||||
- 0x07E-0x07F: R/W registers 18-19 shared by slave and host.
|
||||
- 0x088-0x08B: R/W registers 24-27 shared by slave and host.
|
||||
- 0x09C-0x0BB: R/W registers 32-63 shared by slave and host.
|
||||
|
||||
Interrupt Registers:
|
||||
- 0x08D (SLAVE_INT): bits for host to interrupt slave. auto clear.
|
||||
|
||||
FIFO (sending and receiving)
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
0x090 - 0x1F7FF are reserved for FIFOs.
|
||||
|
||||
The 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:
|
||||
|
||||
*requested length = 0x1F800-address*
|
||||
|
||||
The 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.
|
||||
|
||||
.. note::
|
||||
|
||||
The function number should be set to 1, OP Code should be set to 1 (for CMD53).
|
||||
|
||||
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:
|
||||
|
||||
1. Send CMD53 in block mode, block count=2 (1024 bytes) to address 0x1F3F9=0x1F800-**1031**.
|
||||
2. Then send CMD53 in byte mode, byte count=8 (or 7 if your controller supports that) to address 0x1F7F9=0x1F800-**7**.
|
||||
|
||||
|
||||
Interrupts
|
||||
^^^^^^^^^^
|
||||
|
||||
SDIO 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.
|
||||
|
||||
:cpp:type:`sdio_slave_hostint_t` (:doc:`sdio_slave`) shows the bit definition corresponding to host interrupt sources.
|
||||
|
||||
For 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.
|
||||
|
||||
|
||||
Receiving FIFO
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
To write to the slave's receiving FIFO, the host should complete the following steps:
|
||||
|
||||
1. **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.
|
||||
2. **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.
|
||||
3. **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*.
|
||||
4. **Calculate used buffers**. Note that a partially used buffer at the tail is counted as used.
|
||||
|
||||
|
||||
Sending FIFO
|
||||
^^^^^^^^^^^^
|
||||
|
||||
To read the slave's sending FIFO, the host should complete the following steps:
|
||||
|
||||
1. **Wait for the interrupt line to become active** (optional, low by default).
|
||||
2. **Read (poll) the interrupt bits in the INT_ST register** to monitor if new packets exist.
|
||||
3. **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.
|
||||
4. **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*.
|
||||
5. **Update the read length**.
|
||||
|
||||
@@ -26,6 +26,7 @@ Peripherals API
|
||||
SPI Master <spi_master>
|
||||
SPI Slave <spi_slave>
|
||||
:esp32: Secure Element <secure_element>
|
||||
:esp32s2: SPI Slave Half Duplex <spi_slave_hd>
|
||||
:esp32s2: Temp sensor <temp_sensor>
|
||||
Timer <timer>
|
||||
Touch Sensor <touch_pad>
|
||||
|
||||
@@ -133,10 +133,6 @@ Func 1. Please refer to :ref:`esp_slave_protocol_layer`. There is also a compone
|
||||
for ESP32 master to communicate with ESP32 SDIO slave, see example :example:`peripherals/sdio`
|
||||
when programming your host.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
esp_slave_protocol
|
||||
|
||||
.. _interrupts:
|
||||
|
||||
|
||||
114
docs/en/api-reference/peripherals/spi_slave_hd.rst
Normal file
114
docs/en/api-reference/peripherals/spi_slave_hd.rst
Normal file
@@ -0,0 +1,114 @@
|
||||
SPI Slave Half Duplex
|
||||
=====================
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The half duplex (HD) mode is a special mode provided by ESP SPI Slave peripheral. Under this mode, the hardware provides more services than the full duplex (FD) mode (the mode for general purpose SPI transactions, see :doc:`spi_slave`). These services reduce the CPU load and the response time of SPI Slave, but the communication format is determined by the hardware. The communication format is always half duplex, so comes the name of Half Duplex Mode.
|
||||
|
||||
There are several different types of transactions, determined by the *command* phase of the transaction. Each transaction may consist of the following phases: command, address, dummy, data. The command phase is mandatory, while the other fields may be determined by the command field. During the command, address, dummy phases, the bus is always controlled by the master, while the direction of the data phase depends on the command. The data phase can be either an in phase, for the master to write data to the slave; or an out phase, for the master to read data from the slave.
|
||||
|
||||
About the details of how master should communicate with the SPI Slave, see :doc:`/api-reference/protocols/esp_spi_slave_protocol`.
|
||||
|
||||
By these different transactions, the slave provide these services to the master:
|
||||
|
||||
- A DMA channel for the master to write a great amount of data to the slave.
|
||||
- A DMA channel for the master to read a great amount of data from the slave.
|
||||
- Several general purpose registers, shard between the master and the slave.
|
||||
- Several general purpose interrupts, for the master to interrupt the SW of slave.
|
||||
|
||||
Terminology
|
||||
-----------
|
||||
|
||||
- Transaction
|
||||
- Channel
|
||||
- Sending
|
||||
- Receiving
|
||||
- Data Descriptor
|
||||
|
||||
Driver Feature
|
||||
--------------
|
||||
|
||||
- Transaction read/write by master in segments
|
||||
|
||||
- Queues for data to send and received
|
||||
|
||||
Driver usage
|
||||
------------
|
||||
|
||||
Slave initialization
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Call :cpp:func:`spi_slave_hd_init` to initialize the SPI bus as well as the peripheral and the driver. The SPI slave will exclusively use the SPI peripheral, pins of the bus before it's deinitialized. Most configurations of the slave should be done as soon as the slave is being initialized.
|
||||
|
||||
The :cpp:type:`spi_bus_config_t` specifies how the bus should be initialized, while :cpp:type:`spi_slave_hd_slot_config_t` specifies how the SPI Slave driver should work.
|
||||
|
||||
Deinitialization (optional)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Call :cpp:func:`spi_slave_hd_deinit` to uninstall the driver. The resources, including the pins, SPI peripheral, internal memory used by the driver, interrupt sources, will be released by the deinit function.
|
||||
|
||||
Send/Receive Data by DMA Channels
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To send data to the master through the sending DMA channel, the application should properly wrap the data to send by a :cpp:type:`spi_slave_hd_data_t` descriptor structure before calling :cpp:func:`spi_slave_hd_queue_trans` with the data descriptor, and the channel argument of :cpp:enumerator:`SPI_SLAVE_CHAN_TX`. The pointers to descriptors are stored in the queue, and the data will be send to the master upon master's RDDMA command in the same order they are put into the queue by :cpp:func:`spi_slave_hd_queue_trans`.
|
||||
|
||||
The application should check the result of data sending by calling :cpp:func:`spi_slave_hd_get_trans_res` with the channel set as :cpp:enumerator:`SPI_SLAVE_CHAN_TX`. This function will block until the transaction with command RDDMA from master successfully completes (or timeout). The ``out_trans`` argument of the function will output the pointer of the data descriptor which is just finished.
|
||||
|
||||
Receiving data from the master through the receiving DMA channel is quite similar. The application calls :cpp:func:`spi_slave_hd_queue_trans` with proper data descriptor and the channel argument of :cpp:enumerator:`SPI_SLAVE_CHAN_RX`. And the application calls the :cpp:func:`spi_slave_hd_get_trans_res` later to get the descriptor to the receiving buffer, before it handles the data in the receiving buffer.
|
||||
|
||||
.. note::
|
||||
This driver itself doesn't have internal buffer for the data to send, or just received. The application should provide data descriptors for the data buffer to send to master, or to receive data from the master.
|
||||
|
||||
The application will have to properly keep the data descriptor as well as the buffer it points to, after the descriptor is successfully sent into the driver internal queue by :cpp:func:`spi_slave_hd_queue_trans`, and before returned by :cpp:func:`spi_slave_hd_get_trans_res`. During this period, the hardware as well as the driver may read or write to the buffer and the descriptor when required at any time.
|
||||
|
||||
Please note that the buffer doesn't have to be fully sent or filled before it's terminated. For example, in the segment transaction mode, the master has to send CMD7 to terminate a WRDMA transaction, or send CMD8 to terminate a RDDMA transaction (in segments), no matter the send (receive) buffer is used up (full) or not.
|
||||
|
||||
.. _spi_slave_hd_data_arguments:
|
||||
|
||||
Using Data Arguments
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes you may have initiator (sending data descriptor) and closure (handling returned descriptors) functions in different places. When you get the returned data descriptor in the closure, you may need some extra information when handle the finished data descriptor. For example, you may want to know which round it is for the returned descriptor, when you send the same piece of data for several times.
|
||||
|
||||
Set the ``arg`` member in the data descriptor to an variable indicating the transaction (by force casting), or point it to a a structure which wraps all the information you may need when handling the sending/receiving data. Then you can get what you need in your closure.
|
||||
|
||||
.. _spi_slave_hd_callbacks:
|
||||
|
||||
Using callbacks
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. note::
|
||||
These callbacks are called in the ISR, so that they are fast enough. However, you may need to be very careful to write the code in the ISR. The callback should return as soon as possible. No delay or blocking operations are allowed.
|
||||
|
||||
The :cpp:type:`spi_slave_hd_intr_config_t` member in the :cpp:type:`spi_slave_hd_slot_config_t` configuration structure passed when initialize the SPI Slave HD driver, allows you having callbacks for each events you may concern.
|
||||
|
||||
The corresponding interrupt for each callbacks that is not *NULL* will enabled, so that the callbacks can be called immediately when the events happen. You don't need to provide callbacks for the unconcerned events.
|
||||
|
||||
The ``arg`` member in the configuration structure can help you pass some context to the callback, or indicate which SPI Slave instance when you are using the same callbacks for several SPI Slave peripherals. Set the ``arg`` member to an variable indicating the SPI Slave instance (by force casting), or point it to a context structure. All the callbacks will be called with this ``arg`` argument you set when the callbacks are initialized.
|
||||
|
||||
There are two other arguments: the ``event`` and the ``awoken``. The ``event`` passes the information of the current event to the callback. The :cpp:type:`spi_slave_hd_event_t` type contains the information of the event, for example, event type, the data descriptor just finished (The :ref:`data argument <spi_slave_hd_data_arguments>` will be very useful in this case!). The ``awoken`` argument is an output one, telling the ISR there are tasks are awoken after this callback, and the ISR should call `portYIELD_FROM_ISR()` to do task scheduling. Just pass the ``awoken`` argument to all FreeRTOS APIs which may unblock tasks, and the awoken will be returned to the ISR.
|
||||
|
||||
Writing/Reading Shared Registers
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Call :cpp:func:`spi_slave_hd_write_buffer` to write the shared buffer, and :cpp:func:`spi_slave_hd_read_buffer` to read the shared buffer.
|
||||
|
||||
.. note::
|
||||
On {IDF_TARGET_NAME}, the shared registers are read/written in words by the application, but read/written in bytes by the master. There's no guarantee four continuous bytes read from the master are from the same word written by the slave's application. It's also possible that if the slave reads a word while the master is writing bytes of the word, the slave may get one word with half of them just written by the master, and the other half hasn't been written into.
|
||||
|
||||
The master can confirm that the word is not in transition by reading the word twice and comparing the values.
|
||||
|
||||
For the slave, it will be more difficult to ensure the word is not in transition because the process of master writing four bytes can be very long (32 SPI clocks). You can put some CRC in the last (largest address) byte of a word so that when the byte is written, the word is sure to be all written.
|
||||
|
||||
Due to the conflicts there may be among read/write from SW (worse if there are multi cores) and master, it is suggested that a word is only used in one direction (only written by master or only written by the slave).
|
||||
|
||||
Receiving General Purpose Interrupts From the Master
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When the master sends CMD 0x08, 0x09 or 0x0A, the slave corresponding will be triggered. Currently the CMD8 is permanently used to indicate the termination of RDDMA segments. To receiving general purpose interrupts, register callbacks for CMD 0x09 and 0x0A when the slave is initialized, see :ref:`spi_slave_hd_callbacks`.
|
||||
|
||||
API reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/spi_slave_hd.inc
|
||||
Reference in New Issue
Block a user