mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'feature/update_spi_programming_guide_on_c3_v4.3' into 'release/v4.3'
spi: update spi programming guide on c3 (4.3) See merge request espressif/esp-idf!13280
This commit is contained in:
Michael (XIAO Xufeng)
commit
ed6a0c324c
@ -7,21 +7,34 @@ SPI Master driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals
|
||||
Overview of {IDF_TARGET_NAME}'s SPI peripherals
|
||||
-----------------------------------------------
|
||||
|
||||
ESP32 integrates four SPI peripherals.
|
||||
{IDF_TARGET_MAX_PERIPH_NUM:default="4", esp32c3="3"}
|
||||
{IDF_TARGET_SPI2_CS_NUM:default="6", esp32="3"}
|
||||
{IDF_TARGET_SPI3_CS_NUM:default="3"}
|
||||
|
||||
- SPI0 and SPI1 are used internally to access the ESP32's attached flash memory and share an arbiter.
|
||||
{IDF_TARGET_NAME} integrates {IDF_TARGET_MAX_PERIPH_NUM} SPI peripherals.
|
||||
|
||||
- SPI0 and SPI1 are used internally to access the {IDF_TARGET_NAME}'s attached flash memory. Both controllers share the same SPI bus signals, and there is an arbiter to determine which can access the bus.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
There are quite a few limitations when using SPI Master driver on the SPI1 bus, see
|
||||
:ref:`spi_master_on_spi1_bus`.
|
||||
|
||||
.. only:: esp32s2
|
||||
.. only:: not esp32
|
||||
|
||||
Currently SPI Master driver hasn't supported SPI1 bus.
|
||||
Currently, SPI Master driver does not support SPI1 bus.
|
||||
|
||||
- SPI2 and SPI3 are general purpose SPI controllers, sometimes referred to as HSPI and VSPI, respectively. They are open to users. SPI2 and SPI3 have independent signal buses with the same respective names. Each bus has three CS lines to drive up to three SPI slaves.
|
||||
.. only:: esp32
|
||||
|
||||
- SPI2 and SPI3 are general purpose SPI controllers, sometimes referred to as HSPI and VSPI, respectively. They are open to users. SPI2 and SPI3 have independent bus signals with the same respective names. Each bus has three CS lines to drive up to same number of SPI slaves.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
- SPI2 and SPI3 are general purpose SPI controllers. They are open to users. SPI2 and SPI3 have independent signal buses with the same respective names. SPI2 has {IDF_TARGET_SPI2_CS_NUM} CS lines. SPI3 has {IDF_TARGET_SPI3_CS_NUM} CS lines. Each CS line can be used to drive one SPI slave.
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
- SPI2 is a general purpose SPI controller. It has an independent signal bus with the same name. The bus has {IDF_TARGET_SPI2_CS_NUM} CS lines to drive up to {IDF_TARGET_SPI2_CS_NUM} SPI slaves.
|
||||
|
||||
Terminology
|
||||
-----------
|
||||
@ -31,16 +44,17 @@ The terms used in relation to the SPI master driver are given in the table below
|
||||
================= =========================================================================================
|
||||
Term Definition
|
||||
================= =========================================================================================
|
||||
**Host** The SPI controller peripheral inside ESP32 that initiates SPI transmissions over the bus, and acts as an SPI Master. This may be the SPI2 or SPI3 peripheral. (The driver will also support the SPI1 peripheral in the future.)
|
||||
**Host** The SPI controller peripheral inside {IDF_TARGET_NAME} that initiates SPI transmissions over the bus, and acts as an SPI Master.
|
||||
**Device** SPI slave device. An SPI bus may be connected to one or more Devices. Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Device's individual CS line.
|
||||
**Bus** A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines: MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner.
|
||||
- **MISO** Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host.
|
||||
- **MOSI** Master Out, Slave In, a.k.a. D. Data transmission from a Host to Device.
|
||||
- **SCLK** Serial Clock. Oscillating signal generated by a Host that keeps the transmission of data bits in sync.
|
||||
- **CS** Chip Select. Allows a Host to select individual Device(s) connected to the bus in order to send or receive data.
|
||||
- **QUADWP** Write Protect signal. Only used for 4-bit (qio/qout) transactions.
|
||||
- **QUADHD** Hold signal. Only used for 4-bit (qio/qout) transactions.
|
||||
- **Assertion** The action of activating a line. The opposite action of returning the line back to inactive (back to idle) is called *de-assertion*.
|
||||
**MISO** Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host.
|
||||
**MOSI** Master Out, Slave In, a.k.a. D. Data transmission from a Host to Device.
|
||||
**SCLK** Serial Clock. Oscillating signal generated by a Host that keeps the transmission of data bits in sync.
|
||||
**CS** Chip Select. Allows a Host to select individual Device(s) connected to the bus in order to send or receive data.
|
||||
**QUADWP** Write Protect signal. Only used for 4-bit (qio/qout) transactions.
|
||||
**QUADHD** Hold signal. Only used for 4-bit (qio/qout) transactions.
|
||||
**Assertion** The action of activating a line.
|
||||
**De-assertion** The action of returning the line back to inactive (back to idle) status.
|
||||
**Transaction** One instance of a Host asserting a CS line, transferring data to and from a Device, and de-asserting the CS line. Transactions are atomic, which means they can never be interrupted by another transaction.
|
||||
**Launch edge** Edge of the clock at which the source register *launches* the signal onto the line.
|
||||
**Latch edge** Edge of the clock at which the destination register *latches in* the signal.
|
||||
@ -73,11 +87,13 @@ SPI Transactions
|
||||
|
||||
An SPI bus transaction consists of five phases which can be found in the table below. Any of these phases can be skipped.
|
||||
|
||||
{IDF_TARGET_ADDR_LEN:default="32", esp32="64"}
|
||||
|
||||
============== =========================================================================================================
|
||||
Phase Description
|
||||
============== =========================================================================================================
|
||||
**Command** In this phase, a command (0-16 bit) is written to the bus by the Host.
|
||||
**Address** In this phase, an address (0-64 bit) is transmitted over the bus by the Host.
|
||||
**Address** In this phase, an address (0-{IDF_TARGET_ADDR_LEN} bit) is transmitted over the bus by the Host.
|
||||
**Write** Host sends data to a Device. This data follows the optional command and address phases and is indistinguishable from them at the electrical level.
|
||||
**Dummy** This phase is configurable and is used to meet the timing requirements.
|
||||
**Read** Device sends data to its Host.
|
||||
@ -124,7 +140,7 @@ Polling Transactions
|
||||
|
||||
Polling transactions do not use interrupts. The routine keeps polling the SPI Host's status bit until the transaction is finished.
|
||||
|
||||
All the tasks that use interrupt transactions can be blocked by the queue. At this point, they will need to wait for the ISR to run twice before the transaction is finished. Polling transactions save time otherwise spent on queue handling and context switching, which results in smaller transaction intervals. The disadvantage is that the CPU is busy while these transactions are in progress.
|
||||
All the tasks that use interrupt transactions can be blocked by the queue. At this point, they will need to wait for the ISR to run twice before the transaction is finished. Polling transactions save time otherwise spent on queue handling and context switching, which results in smaller transaction duration. The disadvantage is that the CPU is busy while these transactions are in progress.
|
||||
|
||||
The :cpp:func:`spi_device_polling_end` routine needs an overhead of at least 1 us to unblock other tasks when the transaction is finished. It is strongly recommended to wrap a series of polling transactions using the functions :cpp:func:`spi_device_acquire_bus` and :cpp:func:`spi_device_release_bus` to avoid the overhead. For more information, see :ref:`bus_acquiring`.
|
||||
|
||||
@ -147,10 +163,17 @@ Normally, the data that needs to be transferred to or from a Device will be read
|
||||
|
||||
If these requirements are not satisfied, the transaction efficiency will be affected due to the allocation and copying of temporary buffers.
|
||||
|
||||
.. note::
|
||||
.. only:: esp32
|
||||
|
||||
Half-duplex transactions with both read and write phases are not supported when using DMA. For details and workarounds, see :ref:`spi_known_issues`.
|
||||
.. note::
|
||||
|
||||
Half-duplex transactions with both read and write phases are not supported when using DMA. For details and workarounds, see :ref:`spi_known_issues`.
|
||||
|
||||
.. only:: esp32s3 or esp32c3
|
||||
|
||||
.. note::
|
||||
|
||||
Half-duplex transactions with both read and write phases are not supported. Please use full duplex mode.
|
||||
|
||||
.. _bus_acquiring:
|
||||
|
||||
@ -352,40 +375,42 @@ There are three factors limiting the transfer speed:
|
||||
The main parameter that determines the transfer speed for large transactions is clock frequency. For multiple small transactions, the transfer speed is mostly determined by the length of transaction intervals.
|
||||
|
||||
|
||||
Transaction Interval
|
||||
Transaction Duration
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Transaction interval is the time that software requires to set up SPI peripheral registers and to copy data to FIFOs, or to set up DMA links.
|
||||
{IDF_TARGET_TRANS_TIME_INTR_DMA:default="28", esp32="28", esp32s2="23", esp32c3="28"}
|
||||
{IDF_TARGET_TRANS_TIME_POLL_DMA:default="10", esp32="10", esp32s2="9", esp32c3="10"}
|
||||
{IDF_TARGET_TRANS_TIME_INTR_CPU:default="25", esp32="25", esp32s2="22", esp32c3="27"}
|
||||
{IDF_TARGET_TRANS_TIME_POLL_CPU:default="8", esp32="8", esp32s2="8", esp32c3="9"}
|
||||
|
||||
Transaction duration includes setting up SPI peripheral registers, copying data to FIFOs or setting up DMA links, and the time for SPI transaction.
|
||||
|
||||
Interrupt transactions allow appending extra overhead to accommodate the cost of FreeRTOS queues and the time needed for switching between tasks and the ISR.
|
||||
|
||||
For **interrupt transactions**, the CPU can switch to other tasks when a transaction is in progress. This saves the CPU time but increases the interval. See :ref:`interrupt_transactions`. For **polling transactions**, it does not block the task but allows to do polling when the transaction is in progress. For more information, see :ref:`polling_transactions`.
|
||||
For **interrupt transactions**, the CPU can switch to other tasks when a transaction is in progress. This saves the CPU time but increases the transaction duration. See :ref:`interrupt_transactions`. For **polling transactions**, it does not block the task but allows to do polling when the transaction is in progress. For more information, see :ref:`polling_transactions`.
|
||||
|
||||
If DMA is enabled, setting up the linked list requires about 2 us per transaction. When a master is transferring data, it automatically reads the data from the linked list. If DMA is not enabled, the CPU has to write and read each byte from the FIFO by itself. Usually, this is faster than 2 us, but the transaction length is limited to 64 bytes for both write and read.
|
||||
|
||||
Typical transaction interval timings for one byte of data are given below.
|
||||
|
||||
+--------+----------------+--------------+
|
||||
| | Typical Transaction Time (us) |
|
||||
+========+================+==============+
|
||||
| | Interrupt | Polling |
|
||||
+--------+----------------+--------------+
|
||||
| DMA | 24 | 8 |
|
||||
+--------+----------------+--------------+
|
||||
| No DMA | 22 | 7 |
|
||||
+--------+----------------+--------------+
|
||||
Typical transaction duration for one byte of data are given below.
|
||||
|
||||
- Interrupt Transaction via DMA: {IDF_TARGET_TRANS_TIME_INTR_DMA} µs.
|
||||
- Interrupt Transaction via CPU: {IDF_TARGET_TRANS_TIME_INTR_CPU} µs.
|
||||
- Polling Transaction via DMA: {IDF_TARGET_TRANS_TIME_POLL_DMA} µs.
|
||||
- Polling Transaction via CPU: {IDF_TARGET_TRANS_TIME_POLL_CPU} µs.
|
||||
|
||||
SPI Clock Frequency
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Transferring each byte takes eight times the clock period *8/fspi*. If the clock frequency is too high, the use of some functions might be limited. See :ref:`timing_considerations`.
|
||||
Transferring each byte takes eight times the clock period *8/fspi*.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
If the clock frequency is too high, the use of some functions might be limited. See :ref:`timing_considerations`.
|
||||
|
||||
Cache Miss
|
||||
^^^^^^^^^^
|
||||
|
||||
The default config puts only the ISR into the IRAM. Other SPI related functions, including the driver itself and the callback, might suffer from the cache miss and will need to wait until the code is read from the flash. Select :ref:`CONFIG_SPI_MASTER_IN_IRAM` to put the whole SPI driver into IRAM and put the entire callback(s) and its callee functions into IRAM to prevent cache miss.
|
||||
The default config puts only the ISR into the IRAM. Other SPI related functions, including the driver itself and the callback, might suffer from cache misses and will need to wait until the code is read from flash. Select :ref:`CONFIG_SPI_MASTER_IN_IRAM` to put the whole SPI driver into IRAM and put the entire callback(s) and its callee functions into IRAM to prevent cache misses.
|
||||
|
||||
For an interrupt transaction, the overall cost is *20+8n/Fspi[MHz]* [us] for n bytes transferred in one transaction. Hence, the transferring speed is: *n/(20+8n/Fspi)*. An example of transferring speed at 8 MHz clock speed is given in the following table.
|
||||
|
||||
@ -410,105 +435,105 @@ When a transaction length is short, the cost of transaction interval is high. If
|
||||
Please note that the ISR is disabled during flash operation by default. To keep sending transactions during flash operations, enable :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` and set :cpp:class:`ESP_INTR_FLAG_IRAM` in the member :cpp:member:`spi_bus_config_t::intr_flags`. In this case, all the transactions queued before starting flash operations will be handled by the ISR in parallel. Also note that the callback of each Device and their callee functions should be in IRAM, or your callback will crash due to cache miss. For more details, see :ref:`iram-safe-interrupt-handlers`.
|
||||
|
||||
|
||||
.. _timing_considerations:
|
||||
.. only:: esp32
|
||||
|
||||
Timing Considerations
|
||||
---------------------
|
||||
.. _timing_considerations:
|
||||
|
||||
As shown in the figure below, there is a delay on the MISO line after the SCLK launch edge and before the signal is latched by the internal register. As a result, the MISO pin setup time is the limiting factor for the SPI clock speed. When the delay is too long, the setup slack is < 0, and the setup timing requirement is violated, which results in the failure to perform the reading correctly.
|
||||
Timing Considerations
|
||||
---------------------
|
||||
|
||||
.. image:: /../_static/spi_miso.png
|
||||
:scale: 40 %
|
||||
:align: center
|
||||
As shown in the figure below, there is a delay on the MISO line after the SCLK launch edge and before the signal is latched by the internal register. As a result, the MISO pin setup time is the limiting factor for the SPI clock speed. When the delay is too long, the setup slack is < 0, which means the setup timing requirement is violated and the reading might be incorrect.
|
||||
|
||||
.. wavedrom does not support rendering pdflatex till now(1.3.1), so we use the png here
|
||||
.. image:: /../_static/spi_miso.png
|
||||
:scale: 40 %
|
||||
:align: center
|
||||
|
||||
.. image:: /../_static/miso_timing_waveform.png
|
||||
.. wavedrom does not support rendering pdflatex till now(1.3.1), so we use the png here
|
||||
|
||||
The maximum allowed frequency is dependent on:
|
||||
.. image:: /../_static/miso_timing_waveform.png
|
||||
|
||||
- ``input_delay_ns`` - maximum data valid time on the MISO bus after a clock cycle on SCLK starts
|
||||
- If the IO_MUX pin or the GPIO Matrix is used
|
||||
The maximum allowed frequency is dependent on:
|
||||
|
||||
When the GPIO matrix is used, the maximum allowed frequency is reduced to about 33~77% in comparison to the existing *input delay*. To retain a higher frequency, you have to use the IO_MUX pins or the *dummy bit workaround*. You can obtain the maximum reading frequency of the master by using the function :cpp:func:`spi_get_freq_limit`.
|
||||
- ``input_delay_ns`` - maximum data valid time on the MISO bus after a clock cycle on SCLK starts
|
||||
- If the IO_MUX pin or the GPIO Matrix is used
|
||||
|
||||
.. _dummy_bit_workaround:
|
||||
When the GPIO matrix is used, the maximum allowed frequency is reduced to about 33~77% in comparison to the existing *input delay*. To retain a higher frequency, you have to use the IO_MUX pins or the *dummy bit workaround*. You can obtain the maximum reading frequency of the master by using the function :cpp:func:`spi_get_freq_limit`.
|
||||
|
||||
**Dummy bit workaround**: Dummy clocks, during which the Host does not read data, can be inserted before the read phase begins. The Device still sees the dummy clocks and sends out data, but the Host does not read until the read phase comes. This compensates for the lack of the MISO setup time required by the Host and allows the Host to do reading at a higher frequency.
|
||||
.. _dummy_bit_workaround:
|
||||
|
||||
In the ideal case, if the Device is so fast that the input delay is shorter than an APB clock cycle - 12.5 ns - the maximum frequency at which the Host can read (or read and write) in different conditions is as follows:
|
||||
**Dummy bit workaround**: Dummy clocks, during which the Host does not read data, can be inserted before the read phase begins. The Device still sees the dummy clocks and sends out data, but the Host does not read until the read phase comes. This compensates for the lack of the MISO setup time required by the Host and allows the Host to do reading at a higher frequency.
|
||||
|
||||
+-------------+-------------+------------+-----------------------------+
|
||||
| Frequency Limit (MHz) | Dummy Bits | Comments |
|
||||
+-------------+-------------+ Used + +
|
||||
| GPIO matrix | IO_MUX pins | By Driver | |
|
||||
+=============+=============+============+=============================+
|
||||
| 26.6 | 80 | No | |
|
||||
+-------------+-------------+------------+-----------------------------+
|
||||
| 40 | -- | Yes | Half-duplex, no DMA allowed |
|
||||
+-------------+-------------+------------+-----------------------------+
|
||||
In the ideal case, if the Device is so fast that the input delay is shorter than an APB clock cycle - 12.5 ns - the maximum frequency at which the Host can read (or read and write) in different conditions is as follows:
|
||||
|
||||
If the Host only writes data, the *dummy bit workaround* and the frequency check can be disabled by setting the bit `SPI_DEVICE_NO_DUMMY` in the member :cpp:member:`spi_device_interface_config_t::flags`. When disabled, the output frequency can be 80MHz, even if the GPIO matrix is used.
|
||||
+-------------+-------------+------------+-----------------------------+
|
||||
| Frequency Limit (MHz) | Dummy Bits | Comments |
|
||||
+-------------+-------------+ Used + +
|
||||
| GPIO matrix | IO_MUX pins | By Driver | |
|
||||
+=============+=============+============+=============================+
|
||||
| 26.6 | 80 | No | |
|
||||
+-------------+-------------+------------+-----------------------------+
|
||||
| 40 | -- | Yes | Half-duplex, no DMA allowed |
|
||||
+-------------+-------------+------------+-----------------------------+
|
||||
|
||||
:cpp:member:`spi_device_interface_config_t::flags`
|
||||
If the Host only writes data, the *dummy bit workaround* and the frequency check can be disabled by setting the bit `SPI_DEVICE_NO_DUMMY` in the member :cpp:member:`spi_device_interface_config_t::flags`. When disabled, the output frequency can be 80MHz, even if the GPIO matrix is used.
|
||||
|
||||
The SPI master driver can work even if the :cpp:member:`input_delay_ns` in the structure :cpp:type:`spi_device_interface_config_t` is set to 0. However, setting an accurate value helps to:
|
||||
:cpp:member:`spi_device_interface_config_t::flags`
|
||||
|
||||
- Calculate the frequency limit for full-duplex transactions
|
||||
- Compensate the timing correctly with dummy bits for half-duplex transactions
|
||||
The SPI master driver still works even if the :cpp:member:`input_delay_ns` in the structure :cpp:type:`spi_device_interface_config_t` is set to 0. However, setting an accurate value helps to:
|
||||
|
||||
You can approximate the maximum data valid time after the launch edge of SPI clocks by checking the statistics in the AC characteristics chapter of your Device's specification or measure the time on an oscilloscope or logic analyzer.
|
||||
- Calculate the frequency limit for full-duplex transactions
|
||||
- Compensate the timing correctly with dummy bits for half-duplex transactions
|
||||
|
||||
Please note that the actual PCB layout design and the excessive loads may increase the input delay. It means that non-optimal wiring and/or a load capacitor on the bus will most likely lead to the input delay values exceeding the values given in the Device specification or measured while the bus is floating.
|
||||
You can approximate the maximum data valid time after the launch edge of SPI clocks by checking the statistics in the AC characteristics chapter of your Device's specification or measure the time using an oscilloscope or logic analyzer.
|
||||
|
||||
Some typical delay values are shown in the following table.
|
||||
Please note that the actual PCB layout design and excessive loads may increase the input delay. It means that non-optimal wiring and/or a load capacitor on the bus will most likely lead to input delay values exceeding the values given in the Device specification or measured while the bus is floating.
|
||||
|
||||
+----------------------------------------+------------------+
|
||||
| Device | Input delay (ns) |
|
||||
+========================================+==================+
|
||||
| Ideal Device | 0 |
|
||||
+----------------------------------------+------------------+
|
||||
| ESP32 slave using IO_MUX* | 50 |
|
||||
+----------------------------------------+------------------+
|
||||
| ESP32 slave using GPIO_MUX* | 75 |
|
||||
+----------------------------------------+------------------+
|
||||
| ESP32's slave device is on a different physical chip. |
|
||||
+-----------------------------------------------------------+
|
||||
Some typical delay values are shown in the following table. (These data are retrieved when the slave device is on a different physical chip)
|
||||
|
||||
The MISO path delay (valid time) consists of a slave's *input delay* plus master's *GPIO matrix delay*. This delay determines the frequency limit above which full-duplex transfers will not work as well as the dummy bits used in the half-duplex transactions. The frequency limit is:
|
||||
+----------------------------------------+------------------+
|
||||
| Device | Input delay (ns) |
|
||||
+========================================+==================+
|
||||
| Ideal Device | 0 |
|
||||
+----------------------------------------+------------------+
|
||||
| ESP32 slave using IO_MUX* | 50 |
|
||||
+----------------------------------------+------------------+
|
||||
| ESP32 slave using GPIO_MUX* | 75 |
|
||||
+----------------------------------------+------------------+
|
||||
|
||||
*Freq limit [MHz] = 80 / (floor(MISO delay[ns]/12.5) + 1)*
|
||||
The MISO path delay (valid time) consists of a slave's *input delay* plus master's *GPIO matrix delay*. This delay determines the frequency limit above which full-duplex transfers will not work as well as the dummy bits used in the half-duplex transactions. The frequency limit is:
|
||||
|
||||
The figure below shows the relationship between frequency limit and input delay. Two extra APB clock cycle periods should be added to the MISO delay if the master uses the GPIO matrix.
|
||||
*Freq limit [MHz] = 80 / (floor(MISO delay[ns]/12.5) + 1)*
|
||||
|
||||
.. image:: /../_static/spi_master_freq_tv.png
|
||||
The figure below shows the relationship between frequency limit and input delay. Two extra APB clock cycle periods should be added to the MISO delay if the master uses the GPIO matrix.
|
||||
|
||||
Corresponding frequency limits for different Devices with different *input delay* times are shown in the table below.
|
||||
.. image:: /../_static/spi_master_freq_tv.png
|
||||
|
||||
+--------+------------------+----------------------+-------------------+
|
||||
| Master | Input delay (ns) | MISO path delay (ns) | Freq. limit (MHz) |
|
||||
+========+==================+======================+===================+
|
||||
| IO_MUX | 0 | 0 | 80 |
|
||||
+ (0ns) +------------------+----------------------+-------------------+
|
||||
| | 50 | 50 | 16 |
|
||||
+ +------------------+----------------------+-------------------+
|
||||
| | 75 | 75 | 11.43 |
|
||||
+--------+------------------+----------------------+-------------------+
|
||||
| GPIO | 0 | 25 | 26.67 |
|
||||
+ (25ns) +------------------+----------------------+-------------------+
|
||||
| | 50 | 75 | 11.43 |
|
||||
+ +------------------+----------------------+-------------------+
|
||||
| | 75 | 100 | 8.89 |
|
||||
+--------+------------------+----------------------+-------------------+
|
||||
Corresponding frequency limits for different Devices with different *input delay* times are shown in the table below.
|
||||
|
||||
+--------+------------------+----------------------+-------------------+
|
||||
| Master | Input delay (ns) | MISO path delay (ns) | Freq. limit (MHz) |
|
||||
+========+==================+======================+===================+
|
||||
| IO_MUX | 0 | 0 | 80 |
|
||||
+ (0ns) +------------------+----------------------+-------------------+
|
||||
| | 50 | 50 | 16 |
|
||||
+ +------------------+----------------------+-------------------+
|
||||
| | 75 | 75 | 11.43 |
|
||||
+--------+------------------+----------------------+-------------------+
|
||||
| GPIO | 0 | 25 | 26.67 |
|
||||
+ (25ns) +------------------+----------------------+-------------------+
|
||||
| | 50 | 75 | 11.43 |
|
||||
+ +------------------+----------------------+-------------------+
|
||||
| | 75 | 100 | 8.89 |
|
||||
+--------+------------------+----------------------+-------------------+
|
||||
|
||||
.. _spi_known_issues:
|
||||
|
||||
Known Issues
|
||||
------------
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. _spi_known_issues:
|
||||
|
||||
Known Issues
|
||||
------------
|
||||
|
||||
1. Half-duplex transactions are not compatible with DMA when both writing and reading phases are used.
|
||||
|
||||
If such transactions are required, you have to use one of the alternative solutions:
|
||||
@ -522,7 +547,7 @@ Known Issues
|
||||
|
||||
2. Full-duplex transactions are not compatible with the *dummy bit workaround*, hence the frequency is limited. See :ref:`dummy bit speed-up workaround <dummy_bit_workaround>`.
|
||||
|
||||
3. ``dummy_bits`` in :cpp:type:`spi_device_interface_config_t` and :cpp:type:`spi_transaction_ext_t` are not available when SPI read and write phases are both enabled (regardless of full duplex or half duplex mode).
|
||||
3. ``dummy_bits`` in :cpp:type:`spi_device_interface_config_t` and :cpp:type:`spi_transaction_ext_t` are not available when SPI read and write phases are both enabled (regardless of full duplex or half duplex mode).
|
||||
|
||||
4. ``cs_ena_pretrans`` is not compatible with the command and address phases of full-duplex transactions.
|
||||
|
||||
@ -544,4 +569,3 @@ API Reference - SPI Master
|
||||
--------------------------
|
||||
|
||||
.. include-build-file:: inc/spi_master.inc
|
||||
|
||||
|
||||
@ -7,12 +7,20 @@ SPI Slave driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals
|
||||
Overview of {IDF_TARGET_NAME}'s SPI peripherals
|
||||
-----------------------------------------------
|
||||
|
||||
{IDF_TARGET_NAME} integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master
|
||||
.. only:: esp32 or esp32s2
|
||||
|
||||
- SPI2, sometimes referred to as HSPI
|
||||
- SPI3, sometimes referred to as VSPI
|
||||
{IDF_TARGET_NAME} integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master
|
||||
|
||||
SPI2 and SPI3 have independent signal buses with the same respective names.
|
||||
.. only:: esp32
|
||||
|
||||
- SPI2, sometimes referred to as HSPI
|
||||
- SPI3, sometimes referred to as VSPI
|
||||
|
||||
SPI2 and SPI3 have independent signal buses with the same respective names.
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
{IDF_TARGET_NAME} integrates one general purpose SPI controller which can be used as slave node driven by an off-chip SPI master. The controller is called SPI2 and has an independent signal bus with the same name.
|
||||
|
||||
|
||||
Terminology
|
||||
@ -24,7 +32,7 @@ The terms used in relation to the SPI slave driver are given in the table below.
|
||||
Term Definition
|
||||
================= =========================================================================================
|
||||
**Host** The SPI controller peripheral external to {IDF_TARGET_NAME} that initiates SPI transmissions over the bus, and acts as an SPI Master.
|
||||
**Device** SPI slave device, in this case the SPI2 and SPI3 controllers. Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Device's individual CS line.
|
||||
**Device** SPI slave device (general purpose SPI controller). Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Device's individual CS line.
|
||||
**Bus** A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines: MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner.
|
||||
- **MISO** Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host.
|
||||
- **MOSI** Master In, Slave Out, a.k.a. D. Data transmission from a Host to Device.
|
||||
@ -43,7 +51,9 @@ Term Definition
|
||||
Driver Features
|
||||
---------------
|
||||
|
||||
The SPI slave driver allows using the SPI2 and/or SPI3 peripherals as full-duplex Devices. The driver can send/receive transactions up to 64 bytes in length, or utilize DMA to send/receive longer transactions. However, there are some :ref:`known issues <spi_dma_known_issues>` related to DMA.
|
||||
{IDF_TARGET_MAX_DATA_BUF:default="64", esp32s2="72"}
|
||||
|
||||
The SPI slave driver allows using the SPI peripherals as full-duplex Devices. The driver can send/receive transactions up to {IDF_TARGET_MAX_DATA_BUF} bytes in length, or utilize DMA to send/receive longer transactions. However, there are some :ref:`known issues <spi_dma_known_issues>` related to DMA.
|
||||
|
||||
|
||||
SPI Transactions
|
||||
@ -148,30 +158,34 @@ You can also configure a GPIO pin through which the Device will signal to the Ho
|
||||
SCLK Frequency Requirements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The SPI slaves are designed to operate at up to 10 MHz. The data cannot be recognized or received correctly if the clock is too fast or does not have a 50% duty cycle.
|
||||
{IDF_TARGET_MAX_FREQ:default="40", esp32="10", esp32s2="40", esp32c3="60"}
|
||||
|
||||
On top of that, there are additional requirements for the data to meet the timing constraints:
|
||||
The SPI slaves are designed to operate at up to {IDF_TARGET_MAX_FREQ} MHz. The data cannot be recognized or received correctly if the clock is too fast or does not have a 50% duty cycle.
|
||||
|
||||
- Read (MOSI):
|
||||
The Device can read data correctly only if the data is already set at the launch edge. Although it is usually the case for most masters.
|
||||
.. only:: esp32
|
||||
|
||||
- Write (MISO):
|
||||
The output delay of the MISO signal needs to be shorter than half of a clock cycle period so that the MISO line is stable before the next latch edge. Given that the clock is balanced, the output delay and frequency limitations in different cases are given below.
|
||||
On top of that, there are additional requirements for the data to meet the timing constraints:
|
||||
|
||||
+-------------+---------------------------+------------------------+
|
||||
| | Output delay of MISO (ns) | Freq. limit (MHz) |
|
||||
+=============+===========================+========================+
|
||||
| IO_MUX | 43.75 | <11.4 |
|
||||
+-------------+---------------------------+------------------------+
|
||||
| GPIO matrix | 68.75 | <7.2 |
|
||||
+-------------+---------------------------+------------------------+
|
||||
- Read (MOSI):
|
||||
The Device can read data correctly only if the data is already set at the launch edge. Although it is usually the case for most masters.
|
||||
|
||||
Note:
|
||||
1. If the frequency is equal to the limitation, it can lead to random errors.
|
||||
2. The clock uncertainty between Host and Device (12.5ns) is included.
|
||||
3. The output delay is measured under ideal circumstances (no load). If the MISO pin is heavily loaded, the output delay will be longer, and the maximum allowed frequency will be lower.
|
||||
- Write (MISO):
|
||||
The output delay of the MISO signal needs to be shorter than half of a clock cycle period so that the MISO line is stable before the next latch edge. Given that the clock is balanced, the output delay and frequency limitations in different cases are given below.
|
||||
|
||||
Exception: The frequency is allowed to be higher if the master has more tolerance for the MISO setup time, e.g., latch data at the next edge than expected, or configurable latching time.
|
||||
+-------------+---------------------------+------------------------+
|
||||
| | Output delay of MISO (ns) | Freq. limit (MHz) |
|
||||
+=============+===========================+========================+
|
||||
| IO_MUX | 43.75 | <11.4 |
|
||||
+-------------+---------------------------+------------------------+
|
||||
| GPIO matrix | 68.75 | <7.2 |
|
||||
+-------------+---------------------------+------------------------+
|
||||
|
||||
Note:
|
||||
1. If the frequency is equal to the limitation, it can lead to random errors.
|
||||
2. The clock uncertainty between Host and Device (12.5ns) is included.
|
||||
3. The output delay is measured under ideal circumstances (no load). If the MISO pin is heavily loaded, the output delay will be longer, and the maximum allowed frequency will be lower.
|
||||
|
||||
Exception: The frequency is allowed to be higher if the master has more tolerance for the MISO setup time, e.g., latch data at the next edge, or configurable latching time.
|
||||
|
||||
|
||||
.. _spi_dma_known_issues:
|
||||
@ -183,11 +197,13 @@ Restrictions and Known Issues
|
||||
|
||||
Also, a Host should write lengths that are multiples of 4 bytes. The data with inappropriate lengths will be discarded.
|
||||
|
||||
2. Furthermore, DMA requires SPI modes 1 and 3. For SPI modes 0 and 2, the MISO signal has to be launched half a clock cycle earlier to meet the timing. The new timing is as follows:
|
||||
.. only:: esp32
|
||||
|
||||
.. image:: /../_static/spi_slave_miso_dma.png
|
||||
2. Furthermore, DMA requires SPI modes 1 and 3. For SPI modes 0 and 2, the MISO signal has to be launched half a clock cycle earlier to meet the timing. The new timing is as follows:
|
||||
|
||||
If DMA is enabled, a Device's launch edge is half of an SPI clock cycle ahead of the normal time, shifting to the Master's actual latch edge. In this case, if the GPIO matrix is bypassed, the hold time for data sampling is 68.75 ns and no longer a half of an SPI clock cycle. If the GPIO matrix is used, the hold time will increase to 93.75 ns. The Host should sample the data immediately at the latch edge or communicate in SPI modes 1 or 3. If your Host cannot meet these timing requirements, initialize your Device without DMA.
|
||||
.. image:: /../_static/spi_slave_miso_dma.png
|
||||
|
||||
If DMA is enabled, a Device's launch edge is half of an SPI clock cycle ahead of the normal time, shifting to the Master's actual latch edge. In this case, if the GPIO matrix is bypassed, the hold time for data sampling is 68.75 ns and no longer a half of an SPI clock cycle. If the GPIO matrix is used, the hold time will increase to 93.75 ns. The Host should sample the data immediately at the latch edge or communicate in SPI modes 1 or 3. If your Host cannot meet these timing requirements, initialize your Device without DMA.
|
||||
|
||||
|
||||
Application Example
|
||||
|
||||
Loading…
Reference in New Issue
Block a user