spi_slave: improve the timing configuration

SPI Slave
===========

- Correct the configuration of mode 0~3 using new config in the TRM
- Split the workaround for DMA in mode 0/2 out of normal config, to make it clear.
- Update timing and speed document for the SPI slave.

Resolves https://github.com/espressif/esp-idf/issues/1346, https://github.com/espressif/esp-idf/issues/2393

components/driver/spi_slave.c

@@ -202,26 +202,62 @@ esp_err_t spi_slave_initialize(spi_host_device_t host, const spi_bus_config_t *b
     spihost[host]->hw->slave.sync_reset = 1;
     spihost[host]->hw->slave.sync_reset = 0;
 
-
-    bool nodelay = true;
     spihost[host]->hw->ctrl.rd_bit_order = (slave_config->flags & SPI_SLAVE_RXBIT_LSBFIRST) ? 1 : 0;
     spihost[host]->hw->ctrl.wr_bit_order = (slave_config->flags & SPI_SLAVE_TXBIT_LSBFIRST) ? 1 : 0;
-    if (slave_config->mode == 0) {
-        spihost[host]->hw->pin.ck_idle_edge = 0;
-        spihost[host]->hw->user.ck_i_edge = 1;
-        spihost[host]->hw->ctrl2.miso_delay_mode = nodelay ? 0 : 2;
-    } else if (slave_config->mode == 1) {
-        spihost[host]->hw->pin.ck_idle_edge = 0;
-        spihost[host]->hw->user.ck_i_edge = 0;
-        spihost[host]->hw->ctrl2.miso_delay_mode = nodelay ? 0 : 1;
-    } else if (slave_config->mode == 2) {
+
+    const int mode = slave_config->mode;
+    if (mode == 0) {
+        //The timing needs to be fixed to meet the requirements of DMA
         spihost[host]->hw->pin.ck_idle_edge = 1;
         spihost[host]->hw->user.ck_i_edge = 0;
-        spihost[host]->hw->ctrl2.miso_delay_mode = nodelay ? 0 : 1;
-    } else if (slave_config->mode == 3) {
+        spihost[host]->hw->ctrl2.miso_delay_mode = 0;
+        spihost[host]->hw->ctrl2.miso_delay_num = 0;
+        spihost[host]->hw->ctrl2.mosi_delay_mode = 2;
+        spihost[host]->hw->ctrl2.mosi_delay_num = 2;
+    } else if (mode == 1) {
         spihost[host]->hw->pin.ck_idle_edge = 1;
         spihost[host]->hw->user.ck_i_edge = 1;
-        spihost[host]->hw->ctrl2.miso_delay_mode = nodelay ? 0 : 2;
+        spihost[host]->hw->ctrl2.miso_delay_mode = 2;
+        spihost[host]->hw->ctrl2.miso_delay_num = 0;
+        spihost[host]->hw->ctrl2.mosi_delay_mode = 0;
+        spihost[host]->hw->ctrl2.mosi_delay_num = 0;
+    } else if (mode == 2) {
+        //The timing needs to be fixed to meet the requirements of DMA
+        spihost[host]->hw->pin.ck_idle_edge = 0;
+        spihost[host]->hw->user.ck_i_edge = 1;
+        spihost[host]->hw->ctrl2.miso_delay_mode = 0;
+        spihost[host]->hw->ctrl2.miso_delay_num = 0;
+        spihost[host]->hw->ctrl2.mosi_delay_mode = 1;
+        spihost[host]->hw->ctrl2.mosi_delay_num = 2;
+    } else if (mode == 3) {
+        spihost[host]->hw->pin.ck_idle_edge = 0;
+        spihost[host]->hw->user.ck_i_edge = 0;
+        spihost[host]->hw->ctrl2.miso_delay_mode = 1;
+        spihost[host]->hw->ctrl2.miso_delay_num = 0;
+        spihost[host]->hw->ctrl2.mosi_delay_mode = 0;
+        spihost[host]->hw->ctrl2.mosi_delay_num = 0;
+    }
+
+    /* Silicon issues exists in mode 0 and 2 with DMA, change clock phase to
+     * avoid dma issue. This will cause slave output to appear at most half a
+     * spi clock before
+     */
+    if (dma_chan != 0) {
+        if (mode == 0) {
+            spihost[host]->hw->pin.ck_idle_edge = 0;
+            spihost[host]->hw->user.ck_i_edge = 1;
+            spihost[host]->hw->ctrl2.miso_delay_mode = 0;
+            spihost[host]->hw->ctrl2.miso_delay_num = 2;
+            spihost[host]->hw->ctrl2.mosi_delay_mode = 0;
+            spihost[host]->hw->ctrl2.mosi_delay_num = 3;
+        } else if (mode == 2) {
+            spihost[host]->hw->pin.ck_idle_edge = 1;
+            spihost[host]->hw->user.ck_i_edge = 0;
+            spihost[host]->hw->ctrl2.miso_delay_mode = 0;
+            spihost[host]->hw->ctrl2.miso_delay_num = 2;
+            spihost[host]->hw->ctrl2.mosi_delay_mode = 0;
+            spihost[host]->hw->ctrl2.mosi_delay_num = 3;
+        }
     }
 
     //Reset DMA

components/driver/test/test_spi_slave.c

@@ -17,6 +17,7 @@
 #define PIN_NUM_CLK  19
 #define PIN_NUM_CS   22
 
+
 static const char MASTER_TAG[] = "test_master";
 static const char SLAVE_TAG[] = "test_slave";
 
@@ -45,7 +46,8 @@ static void master_init_nodma( spi_device_handle_t* spi)
         .spics_io_num=PIN_NUM_CS,               //CS pin
         .queue_size=7,                          //We want to be able to queue 7 transactions at a time
         .pre_cb=NULL,
-        .cs_ena_posttrans=1,
+        .cs_ena_posttrans=5,
+        .cs_ena_pretrans=1,
     };
     //Initialize the SPI bus
     ret=spi_bus_initialize(HSPI_HOST, &buscfg, 0);

docs/_static/diagrams/spi/spi_slave_miso_dma.rst

@@ -0,0 +1,23 @@
+.. This is the source code to generate figure by https://wavedrom.com/.
+.. We can use the sphinx plugin sphinxcontrib-wavedrom to generate the figure and put it in the html doc (by include this source code), but it is not supported by the pdf. Currently we generate the figure manually and include the stataic figure in the doc.
+
+.. wavedrom::
+
+    { signal: [
+      { name:'CS', 		wave:'10........'},
+      { name: 'SCLK',	wave: '0.10101010',  node: '...ab'},
+      { name: 'MISO (normal)', 	wave: 'x3.3.3.3.3',  node: '...c.d', data: ['7','6','5','4','3'], phase:-0.8},
+      { name: 'SCLK',	wave: '0.10101010',  node: '..e.f'},
+      { name: 'MISO (DMA)', 	wave: 'x33.3.3.3',  node: '..g.h', data: ['7','6','5','4','3','2'], phase:-0.8},
+      ],
+      edge: [
+        'a|->c delay',
+        'b-|->c setup',
+        'b-|->d hold',
+      	'e|->g delay',
+      	'f|->g setup',
+      	'f-|>h hold',
+      ],
+     config:{hscale: 2}
+    }
+

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

@@ -13,8 +13,10 @@ connected SPI master.
 The spi_slave driver
 ^^^^^^^^^^^^^^^^^^^^^
 
-The spi_slave driver allows using the HSPI and/or VSPI peripheral as a full-duplex SPI slave. It can make
-use of DMA to send/receive transactions of arbitrary length.
+The spi_slave driver allows using the HSPI and/or VSPI peripheral as a
+full-duplex SPI slave. It can send/receive transactions within 64 bytes, or
+make use of DMA to send/receive transactions longer than that. However, there
+are some `known issues <spi_dma_known_issues>`_ when the DMA is enabled.
 
 Terminology
 ^^^^^^^^^^^
@@ -47,6 +49,54 @@ starts sending out clock pulses on the CLK line: every clock pulse causes a data
 the master to the slave on the MOSI line and vice versa on the MISO line. At the end of the transaction,
 the master makes CS high again.
 
+.. note:: The SPI slave peripheral relies on the control of software very
+   much. The master shouldn't start a transaction when the slave hasn't prepared
+   for it. Using one more GPIO as the handshake signal to sync is a good idea.
+   For more details, see :ref:`transaction_interval`.
+
+GPIO matrix and IOMUX
+^^^^^^^^^^^^^^^^^^^^^
+
+Most peripheral signals in ESP32 can connect directly to a specific GPIO,
+which is called its IOMUX pin. When a peripheral signal is routed to a pin
+other than its IOMUX pin, ESP32 uses the less direct GPIO matrix to make this
+connection.
+
+If the driver is configured with all SPI signals set to their specific IOMUX
+pins (or left unconnected), it will bypass the GPIO matrix. If any SPI signal
+is configured to a pin other than its IOMUx pin, the driver will
+automatically route all the signals via the GPIO Matrix. The GPIO matrix
+samples all signals at 80MHz and sends them between the GPIO and the
+peripheral.
+
+When the GPIO matrix is used, setup time of MISO is more easily violated,
+since the output delay of MISO signal is increased.
+
+.. note:: More details about influence of output delay on the maximum clock
+  frequency, see :ref:`timing_considerations` below.
+
+IOMUX pins for SPI controllers are as below:
+
++----------+------+------+
+| Pin Name | HSPI | VSPI |
++          +------+------+
+|          | GPIO Number |
++==========+======+======+
+| CS0*     | 15   | 5    |
++----------+------+------+
+| SCLK     | 14   | 18   |
++----------+------+------+
+| MISO     | 12   | 19   |
++----------+------+------+
+| MOSI     | 13   | 23   |
++----------+------+------+
+| QUADWP   | 2    | 22   |
++----------+------+------+
+| QUADHD   | 4    | 21   |
++----------+------+------+
+
+note * Only the first device attaching to the bus can use CS0 pin.
+
 Using the spi_slave driver
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -85,6 +135,73 @@ Warning: Due to a design peculiarity in the ESP32, if the amount of bytes sent b
 of the transmission queues in the slave driver, in bytes, is not both larger than eight and dividable by
 four, the SPI hardware can fail to write the last one to seven bytes to the receive buffer.
 
+Speed and Timing considerations
+-------------------------------
+
+.. _transaction_interval:
+
+Transaction interval
+^^^^^^^^^^^^^^^^^^^^
+
+The SPI slave is designed as s general purpose device controlled by the CPU.
+Different from dedicated devices, CPU-based SPI slave doesn't have too much
+pre-defined registers. All transactions should be triggered by the CPU, which
+means the response speed would not be real-time, and there'll always be
+noticeable intervals between transfers.
+
+During the transaction intervals, the device is not prepared for
+transactions, the response is not meaningful at all. It is suggested to use
+:cpp:func:`spi_slave_queue_trans` with :cpp:func:`spi_slave_get_trans_result`
+to shorten the interval to half the case when using
+:cpp:func:`spi_slave_transmit`.
+
+The master should always wait for the slave to be ready to start new
+transactions. Suggested way is to use a gpio by the slave to indicate whether
+it's ready. The example is in :example:`peripherals/spi_slave`.
+
+SCLK frequency requirement
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The spi slave is designed to work under 10MHz or lower. The clock and data
+cannot be recognized or received correctly if the clock is too fast or
+doesn't have a 50% duty cycle.
+
+Moreover, there are more requirements if the data meets the timing
+requirement:
+
+- Read (MOSI):
+    Given that the MOSI is valid right at the launch edge, the slave can
+    read data correctly. Luckily, it's usually the case for most masters.
+
+- Write (MISO):
+    To meet the requirement that MISO is stable before the next latch edge of
+    SPI clock, the output delay of MISO signal should be shorter than half a
+    clock. The output delay and frequency limitation (given that the clock is
+    balanced) of different cases are as below :
+
+    +-------------+---------------------------+------------------------+
+    |             | Output delay of MISO (ns) | Freq. limit (MHZ)      |
+    +=============+===========================+========================+
+    | IOMUX       | 43.75                     | <11.4                  |
+    +-------------+---------------------------+------------------------+
+    | GPIO matrix | 68.75                     | <7.2                   |
+    +-------------+---------------------------+------------------------+
+
+    Note:
+      1. Random error will happen if the frequency exactly equals the
+         limitation
+      2. The clock uncertainty between master and slave (12.5ns) is
+         included.
+      3. The output delay is measured under ideal case (free of load). When
+         the loading of MISO pin is too heavy, the output delay will be longer,
+         and the maximum allowed frequency will be lower.
+
+    There is an exceptions: The frequency is allowed to be higher if the
+    master has more toleration for the MISO setup time, e.g. latch data at
+    the next edge than expected, or configurable latching time.
+
+.. _spi_dma_known_issues:
+
 Restrictions and Known issues
 -------------------------------
 
@@ -96,6 +213,17 @@ Restrictions and Known issues
    Also, master should write lengths which are a multiple of 4 bytes. Data
    longer than that will be discarded.
 
+2. Furthurmore, the DMA requires a spi mode 1/3 timing. When using spi mode
+   0/2, the MISO signal has to output half a clock earlier to meet the timing.
+   The new timing is as below:
+
+  .. image:: /../_static/spi_slave_miso_dma.png
+
+  The hold time after the latch edge is 68.75ns (when GPIO matrix is
+  bypassed), no longer half a SPI clock. The master should sample immediately
+  at the latch edge, or communicate in mode 1/3. Or just initial the spi
+  slave without DMA.
+
 Application Example
 -------------------