espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-07-31 19:24:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feature/update_spi_programming_guide_on_c3_v4.3' into 'release/v4.3'

Browse Source 
spi: update spi programming guide on c3 (4.3)

See merge request espressif/esp-idf!13280
This commit is contained in:
Michael (XIAO Xufeng)
2021-04-23 06:44:03 +00:00
parent c6ca4e3e88 d7a793f406
commit ed6a0c324c
2 changed files with 170 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
docs/en/api-reference/peripherals/spi_master.rst
View File

@@ -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 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 .. only:: esp32
There are quite a few limitations when using SPI Master driver on the SPI1 bus, see There are quite a few limitations when using SPI Master driver on the SPI1 bus, see
:ref:`spi_master_on_spi1_bus`. :ref:`spi_master_on_spi1_bus`.
.. only:: not esp32
Currently, SPI Master driver does not support SPI1 bus.
.. 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 .. only:: esp32s2
Currently SPI Master driver hasn't supported SPI1 bus. - 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.
- 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:: 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 Terminology
----------- -----------
@@ -31,16 +44,17 @@ The terms used in relation to the SPI master driver are given in the table below
================= ========================================================================================= ================= =========================================================================================
Term Definition 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. **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. **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. **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. **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. **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. **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. **QUADWP** Write Protect signal. Only used for 4-bit (qio/qout) transactions.
- **QUADHD** Hold 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*. **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. **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. **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. **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. 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 Phase Description
============== ========================================================================================================= ============== =========================================================================================================
**Command** In this phase, a command (0-16 bit) is written to the bus by the Host. **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. **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. **Dummy** This phase is configurable and is used to meet the timing requirements.
**Read** Device sends data to its Host. **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. 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`. 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. If these requirements are not satisfied, the transaction efficiency will be affected due to the allocation and copying of temporary buffers.
.. only:: esp32
.. note:: .. 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`. 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: .. _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. 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. 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. 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 duration for one byte of data are given below.
+--------+----------------+--------------+
| | Typical Transaction Time (us) |
+========+================+==============+
| | Interrupt | Polling |
+--------+----------------+--------------+
| DMA | 24 | 8 |
+--------+----------------+--------------+
| No DMA | 22 | 7 |
+--------+----------------+--------------+
- 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 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 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. 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,12 +435,14 @@ 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`. 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`.
.. only:: esp32
.. _timing_considerations: .. _timing_considerations:
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. 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.
.. image:: /../_static/spi_miso.png .. image:: /../_static/spi_miso.png
:scale: 40 % :scale: 40 %
@@ -452,16 +479,16 @@ If the Host only writes data, the *dummy bit workaround* and the frequency check
:cpp:member:`spi_device_interface_config_t::flags` :cpp:member:`spi_device_interface_config_t::flags`
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: 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:
- Calculate the frequency limit for full-duplex transactions - Calculate the frequency limit for full-duplex transactions
- Compensate the timing correctly with dummy bits for half-duplex transactions - Compensate the timing correctly with dummy bits for half-duplex transactions
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. 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.
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. 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.
Some typical delay values are shown in the following table. Some typical delay values are shown in the following table. (These data are retrieved when the slave device is on a different physical chip)
+----------------------------------------+------------------+ +----------------------------------------+------------------+
| Device | Input delay (ns) | | Device | Input delay (ns) |
@@ -472,8 +499,6 @@ Some typical delay values are shown in the following table.
+----------------------------------------+------------------+ +----------------------------------------+------------------+
| ESP32 slave using GPIO_MUX* | 75 | | ESP32 slave using GPIO_MUX* | 75 |
+----------------------------------------+------------------+ +----------------------------------------+------------------+
| ESP32's 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: 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:
@@ -502,13 +527,13 @@ Corresponding frequency limits for different Devices with different *input delay
+--------+------------------+----------------------+-------------------+ +--------+------------------+----------------------+-------------------+
.. only:: esp32
.. _spi_known_issues: .. _spi_known_issues:
Known Issues Known Issues
------------ ------------
.. only:: esp32
1. Half-duplex transactions are not compatible with DMA when both writing and reading phases are used. 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: If such transactions are required, you have to use one of the alternative solutions:
@@ -544,4 +569,3 @@ API Reference - SPI Master
-------------------------- --------------------------
.. include-build-file:: inc/spi_master.inc .. include-build-file:: inc/spi_master.inc

24
docs/en/api-reference/peripherals/spi_slave.rst
View File

@@ -7,13 +7,21 @@ SPI Slave driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals
Overview of {IDF_TARGET_NAME}'s SPI peripherals Overview of {IDF_TARGET_NAME}'s SPI peripherals
----------------------------------------------- -----------------------------------------------
.. only:: esp32 or esp32s2
{IDF_TARGET_NAME} integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master {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
- SPI2, sometimes referred to as HSPI - SPI2, sometimes referred to as HSPI
- SPI3, sometimes referred to as VSPI - SPI3, sometimes referred to as VSPI
SPI2 and SPI3 have independent signal buses with the same respective names. 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 Terminology
----------- -----------
@@ -24,7 +32,7 @@ The terms used in relation to the SPI slave driver are given in the table below.
Term Definition 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. **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. **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. - **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. - **MOSI** Master In, Slave Out, a.k.a. D. Data transmission from a Host to Device.
@@ -43,7 +51,9 @@ Term Definition
Driver Features 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 SPI Transactions
@@ -148,7 +158,11 @@ You can also configure a GPIO pin through which the Device will signal to the Ho
SCLK Frequency Requirements 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"}
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.
.. only:: esp32
On top of that, there are additional requirements for the data to meet the timing constraints: On top of that, there are additional requirements for the data to meet the timing constraints:
@@ -171,7 +185,7 @@ On top of that, there are additional requirements for the data to meet the timin
2. The clock uncertainty between Host and Device (12.5ns) is included. 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. 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 than expected, or configurable latching time. 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: .. _spi_dma_known_issues:
@@ -183,6 +197,8 @@ Restrictions and Known Issues
Also, a Host should write lengths that are multiples of 4 bytes. The data with inappropriate lengths will be discarded. Also, a Host should write lengths that are multiples of 4 bytes. The data with inappropriate lengths will be discarded.
.. only:: esp32
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: 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:
.. image:: /../_static/spi_slave_miso_dma.png .. image:: /../_static/spi_slave_miso_dma.png