From 58955a79a27d3c7331eaec6e464878df42615a36 Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 25 Jun 2018 12:34:31 +0800 Subject: [PATCH] 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 | 64 +++++++-- components/driver/test/test_spi_slave.c | 4 +- .../miso_timing_waveform.rst | 0 .../miso_timing_waveform_async.rst | 0 .../spi_master_freq_tv.plt | 0 .../diagrams/spi/spi_slave_miso_dma.rst | 23 +++ .../{spi_master => spi}/spi_timing.pptx | Bin .../diagrams/{spi_master => spi}/tv.csv | 0 docs/_static/spi_slave_miso_dma.png | Bin 0 -> 25734 bytes .../api-reference/peripherals/spi_slave.rst | 132 +++++++++++++++++- 10 files changed, 206 insertions(+), 17 deletions(-) rename docs/_static/diagrams/{spi_master => spi}/miso_timing_waveform.rst (100%) rename docs/_static/diagrams/{spi_master => spi}/miso_timing_waveform_async.rst (100%) rename docs/_static/diagrams/{spi_master => spi}/spi_master_freq_tv.plt (100%) create mode 100644 docs/_static/diagrams/spi/spi_slave_miso_dma.rst rename docs/_static/diagrams/{spi_master => spi}/spi_timing.pptx (100%) rename docs/_static/diagrams/{spi_master => spi}/tv.csv (100%) create mode 100644 docs/_static/spi_slave_miso_dma.png diff --git a/components/driver/spi_slave.c b/components/driver/spi_slave.c index 31606ac2af..02dd587df9 100644 --- a/components/driver/spi_slave.c +++ b/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 diff --git a/components/driver/test/test_spi_slave.c b/components/driver/test/test_spi_slave.c index c468973faf..bee3fada69 100644 --- a/components/driver/test/test_spi_slave.c +++ b/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); diff --git a/docs/_static/diagrams/spi_master/miso_timing_waveform.rst b/docs/_static/diagrams/spi/miso_timing_waveform.rst similarity index 100% rename from docs/_static/diagrams/spi_master/miso_timing_waveform.rst rename to docs/_static/diagrams/spi/miso_timing_waveform.rst diff --git a/docs/_static/diagrams/spi_master/miso_timing_waveform_async.rst b/docs/_static/diagrams/spi/miso_timing_waveform_async.rst similarity index 100% rename from docs/_static/diagrams/spi_master/miso_timing_waveform_async.rst rename to docs/_static/diagrams/spi/miso_timing_waveform_async.rst diff --git a/docs/_static/diagrams/spi_master/spi_master_freq_tv.plt b/docs/_static/diagrams/spi/spi_master_freq_tv.plt similarity index 100% rename from docs/_static/diagrams/spi_master/spi_master_freq_tv.plt rename to docs/_static/diagrams/spi/spi_master_freq_tv.plt diff --git a/docs/_static/diagrams/spi/spi_slave_miso_dma.rst b/docs/_static/diagrams/spi/spi_slave_miso_dma.rst new file mode 100644 index 0000000000..afa2a69a4a --- /dev/null +++ b/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} + } + diff --git a/docs/_static/diagrams/spi_master/spi_timing.pptx b/docs/_static/diagrams/spi/spi_timing.pptx similarity index 100% rename from docs/_static/diagrams/spi_master/spi_timing.pptx rename to docs/_static/diagrams/spi/spi_timing.pptx diff --git a/docs/_static/diagrams/spi_master/tv.csv b/docs/_static/diagrams/spi/tv.csv similarity index 100% rename from docs/_static/diagrams/spi_master/tv.csv rename to docs/_static/diagrams/spi/tv.csv diff --git a/docs/_static/spi_slave_miso_dma.png b/docs/_static/spi_slave_miso_dma.png new file mode 100644 index 0000000000000000000000000000000000000000..c0e48cd0f89c9ea17dd964e72f2f20dca1ad003d GIT binary patch literal 25734 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 ke|c2kzW&SIr-#`5@6>0o49qb)R&d`_ 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 -------------------