From deda0091d9618f0b0cc23de47e91823f3e5018c4 Mon Sep 17 00:00:00 2001 From: Kirill Chalov Date: Thu, 11 Jul 2019 19:00:58 +0800 Subject: [PATCH] Review the file api-reference/peripherals/spi_master.rst. --- docs/_static/miso_timing_waveform_async.png | Bin 22020 -> 0 bytes .../api-reference/peripherals/spi_master.rst | 601 ++++++++---------- 2 files changed, 259 insertions(+), 342 deletions(-) delete mode 100644 docs/_static/miso_timing_waveform_async.png diff --git a/docs/_static/miso_timing_waveform_async.png b/docs/_static/miso_timing_waveform_async.png deleted file mode 100644 index 4cf84e2daf4aab9f3e97e736119e6bff65ad8eda..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 22020 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 ZpZw!@6LaR?5i10VdAj`, this means using ``pvPortMallocCaps(size, MALLOC_CAP_DMA)``. + 2. 32-bit aligned (staring from a 32-bit boundary and having a length of multiples of 4 bytes). -If these requirements are not satisfied, efficiency of the transaction will suffer due to the allocation and -memcpy of temporary buffers. +If these requirements are not satisfied, the transaction efficiency will be affected due to the allocation and copying of temporary buffers. + +.. 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`. -.. note:: Half duplex transactions with both read and write phases are not supported when using DMA. See - :ref:`spi_known_issues` for details and workarounds. .. _bus_acquiring: -Bus acquiring +Bus Acquiring ^^^^^^^^^^^^^ -Sometimes you may want to send spi transactions exclusively, continuously, to -make it as fast as possible. You may use ``spi_device_acquire_bus`` and -``spi_device_release_bus`` to realize this. When the bus is acquired, -transactions to other devices (no matter polling or interrupt) are pending -until the bus is released. +Sometimes you might want to send SPI transactions exclusively and continuously so that it takes as little time as possible. For this, you can use bus acquiring, which helps to suspend transactions (both polling or interrupt) to other devices until the bus is released. To acquire and release a bus, use the functions :cpp:func:`spi_device_acquire_bus` and :cpp:func:`spi_device_release_bus`. -Using the spi_master driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- Initialize a SPI bus by calling ``spi_bus_initialize``. Make sure to set the correct IO pins in - the ``bus_config`` struct. Take care to set signals that are not needed to -1. +Driver Usage +------------ -- Tell the driver about a SPI slave device connected to the bus by calling spi_bus_add_device. - Make sure to configure any timing requirements the device has in the ``dev_config`` structure. - You should now have a handle for the device, to be used when sending it a transaction. +.. todo:: -- To interact with the device, fill one or more spi_transaction_t structure with any transaction - parameters you need. Then send them either in a polling way or the interrupt way: + Organize the Driver Usage into subsections that will reflect the general usage experience of the users, e.g., + + Configuration + + Add stuff about the configuration API here, and the various options in configuration (e.g., configure for interrupt vs. polling), and optional configuration + + Transactions + + Describe how to execute a normal transaction (i.e., where data is larger than 32 bits). Describe how to configure between big and little-endian. + + - Add subsub section on how to optimize when transmitting less than 32 bits + - Add subsub section on how to transmit mixed transactions to the same device + + +- Initialize an SPI bus by calling the function :cpp:func:`spi_bus_initialize`. Make sure to set the correct I/O pins in the struct :cpp:type:`spi_bus_config_t`. Set the signals that are not needed to ``-1``. + +- Register a Device connected to the bus with the driver by calling the function :cpp:func:`spi_bus_add_device`. Make sure to configure any timing requirements the device might need with the parameter ``dev_config``. You should now have obtained the Device's handle which will be used when sending a transaction to it. + +- To interact with the Device, fill one or more :cpp:type:`spi_transaction_t` structs with any transaction parameters required. Then send the structs either using a polling transaction or an interrupt transaction: - :ref:`Interrupt ` - Either queue all transactions by calling ``spi_device_queue_trans``, - and at a later time query the result using - ``spi_device_get_trans_result``, or handle all requests - synchroneously by feeding them into ``spi_device_transmit``. + Either queue all transactions by calling the function :cpp:func:`spi_device_queue_trans` and, at a later time, query the result using the function :cpp:func:`spi_device_get_trans_result`, or handle all requests synchronously by feeding them into :cpp:func:`spi_device_transmit`. - :ref:`Polling ` - Call the ``spi_device_polling_transmit`` to send polling - transactions. Alternatively, you can send a polling transaction by - ``spi_device_polling_start`` and ``spi_device_polling_end`` if you - want to insert something between them. + Call the function :cpp:func:`spi_device_polling_transmit` to send polling transactions. Alternatively, if you want to insert something in between, send the transactions by using :cpp:func:`spi_device_polling_start` and :cpp:func:`spi_device_polling_end`. -- Optional: to do back-to-back transactions to a device, call - ``spi_device_acquire_bus`` before and ``spi_device_release_bus`` after the - transactions. +- (Optional) To perform back-to-back transactions with a Device, call the function :cpp:func:`spi_device_acquire_bus` before sending transactions and :cpp:func:`spi_device_release_bus` after the transactions have been sent. -- Optional: to unload the driver for a device, call ``spi_bus_remove_device`` with the device - handle as an argument +- (Optional) To unload the driver for a certain Device, call :cpp:func:`spi_bus_remove_device` with the Device handle as an argument. -- Optional: to remove the driver for a bus, make sure no more drivers are attached and call - ``spi_bus_free``. +- (Optional) To remove the driver for a bus, make sure no more drivers are attached and call :cpp:func:`spi_bus_free`. -Tips -"""" +The example code for the SPI master driver can be found in the :example:`peripherals/spi_master` directory of ESP-IDF examples. -1. Transactions with small amount of data: - Sometimes, the amount of data is very small making it less than optimal allocating a separate buffer - for it. If the data to be transferred is 32 bits or less, it can be stored in the transaction struct - itself. For transmitted data, use the ``tx_data`` member for this and set the ``SPI_TRANS_USE_TXDATA`` flag - on the transmission. For received data, use ``rx_data`` and set ``SPI_TRANS_USE_RXDATA``. In both cases, do - not touch the ``tx_buffer`` or ``rx_buffer`` members, because they use the same memory locations - as ``tx_data`` and ``rx_data``. -2. Transactions with integers other than uint8_t - The SPI peripheral reads and writes the memory byte-by-byte. By default, - the SPI works at MSB first mode, each bytes are sent or received from the - MSB to the LSB. However, if you want to send data with length which is - not multiples of 8 bits, unused bits are sent. +Transactions with Data Not Exceeding 32 Bits +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - E.g. you write ``uint8_t data = 0x15`` (00010101B), and set length to - only 5 bits, the sent data is ``00010B`` rather than expected ``10101B``. +When the transaction data size is equal to or less than 32 bits, it will be sub-optimal to allocate a buffer for the data. The data can be directly stored in the transaction struct instead. For transmitted data, it can be achieved by using the :cpp:member:`tx_data` member and setting the :cpp:type:`SPI_TRANS_USE_TXDATA` flag on the transmission. For received data, use :cpp:member:`rx_data` and set :cpp:type:`SPI_TRANS_USE_RXDATA`. In both cases, do not touch the :cpp:member:`tx_buffer` or :cpp:member:`rx_buffer` members, because they use the same memory locations as :cpp:member:`tx_data` and :cpp:member:`rx_data`. - Moreover, ESP32 is a little-endian chip whose lowest byte is stored at - the very beginning address for uint16_t and uint32_t variables. Hence if - a uint16_t is stored in the memory, it's bit 7 is first sent, then bit 6 - to 0, then comes its bit 15 to bit 8. - To send data other than uint8_t arrays, macros ``SPI_SWAP_DATA_TX`` is - provided to shift your data to the MSB and swap the MSB to the lowest - address; while ``SPI_SWAP_DATA_RX`` can be used to swap received data - from the MSB to it's correct place. +Transactions with Integers Other Than ``uint8_t`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -GPIO matrix and IOMUX -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +An SPI Host reads and writes data into memory byte by byte. By default, data is sent with the most significant bit (MSB) first, as LSB first used in rare cases. If a value less than 8 bits needs to be sent, the bits should be written into memory in the MSB first manner. -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. +For example, if ``0b00010`` needs to be sent, it should be written into a ``uint8_t`` variable, and the length for reading should be set to 5 bits. The Device will still receive 8 bits with 3 additional "random" bits, so the reading must be performed correctly. -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. +On top of that, ESP32 is a little-endian chip, which means that the least significant byte of ``uint16_t`` and ``uint32_t`` variables is stored at the smallest address. Hence, if ``uint16_t`` is stored in memory, bits [7:0] are sent first, followed by bits [15:8]. -When the GPIO matrix is used, signals faster than 40MHz cannot propagate and the setup time of MISO is more easily -violated, since the input delay of MISO signal is increased. The maximum clock frequency with GPIO Matrix is 40MHz -or less, whereas using all IOMUX pins allows 80MHz. +For cases when the data to be transmitted has the size differing from ``uint8_t`` arrays, the following macros can be used to transform data to the format that can be sent by the SPI driver directly: -.. note:: More details about influence of input delay on the maximum clock frequency, see :ref:`timing_considerations` below. +- :c:macro:`SPI_SWAP_DATA_TX` for data to be transmitted +- :c:macro:`SPI_SWAP_DATA_RX` for data received -IOMUX pins for SPI controllers are as below: + +.. _mixed_transactions: + +Notes on Sending Mixed Transactions to the Same Device +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To reduce coding complexity, send only one type of transactions (interrupt or polling) to one Device. However, you still can send both interrupt and polling transactions alternately. The notes below explain how to do this. + +The polling transactions should be initiated only after all the polling and interrupt transactions are finished. + +Since an unfinished polling transaction blocks other transactions, please do not forget to call the function :cpp:func:`spi_device_polling_end` after :cpp:func:`spi_device_polling_start` to allow other transactions or to allow other Devices to use the bus. Remember that if there is no need to switch to other tasks during your polling transaction, you can initiate a transaction with :cpp:func:`spi_device_polling_transmit` so that it will be ended automatically. + +In-flight polling transactions are disturbed by the ISR operation to accommodate interrupt transactions. Always make sure that all the interrupt transactions sent to the ISR are finished before you call :cpp:func:`spi_device_polling_start`. To do that, you can keep calling :cpp:func:`spi_device_get_trans_result` until all the transactions are returned. + +To have better control of the calling sequence of functions, send mixed transactions to the same Device only within a single task. + + +GPIO Matrix and IO_MUX +---------------------- + +Most of ESP32's peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. + +The GPIO matrix introduces flexibility of routing but also brings the following disadvantages: + +- Increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins. +- Allows signals with clock frequencies only up to 40 MHz, as opposed to 80 MHz if IO_MUX pins are used. + +.. note:: + + For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`. + +The IO_MUX pins for SPI buses are given below. +----------+------+------+ -| Pin Name | HSPI | VSPI | +| Pin Name | SPI2 | SPI3 | + +------+------+ | | GPIO Number | +==========+======+======+ @@ -267,98 +257,64 @@ IOMUX pins for SPI controllers are as below: | QUADHD | 4 | 21 | +----------+------+------+ -note * Only the first device attaching to the bus can use CS0 pin. +* Only the first Device attached to the bus can use the CS0 pin. -.. _mixed_transactions: - -Notes to send mixed transactions to the same device -""""""""""""""""""""""""""""""""""""""""""""""""""" - -Though we suggest to send only one type (interrupt or polling) of -transactions to one device to reduce coding complexity, it is supported to -send both interrupt and polling transactions alternately. Notes below is to -help you do this. - -The polling transactions should be started when all the other transactions -are finished, no matter they are polling or interrupt. - -An unfinished polling transaction forbid other transactions from being sent. -Always call ``spi_device_polling_end`` after ``spi_device_polling_start`` to -allow other device using the bus, or allow other transactions to be started -to the same device. You can use ``spi_device_polling_transmit`` to simplify -this if you don't need to do something during your polling transaction. - -An in-flight polling transaction would get disturbed by the ISR operation -caused by interrupt transactions. Always make sure all the interrupt -transactions sent to the ISR are finished before you call -``spi_device_polling_start``. To do that, you can call -``spi_device_get_trans_result`` until all the transactions are returned. - -It is strongly recommended to send mixed transactions to the same device in -only one task to control the calling sequence of functions. - -Speed and Timing Considerations -------------------------------- .. _speed_considerations: -Transferring speed -^^^^^^^^^^^^^^^^^^ +Transfer Speed Considerations +----------------------------- -There're three factors limiting the transferring speed: (1) The transaction interval, (2) The SPI clock frequency used. -(3) The cache miss of SPI functions including callbacks. -When large transactions are used, the clock frequency determines the transferring speed; while the interval effects the -speed a lot if small transactions are used. +There are three factors limiting the transfer speed: - 1. Transaction interval: It takes time for the software to setup spi - peripheral registers as well as copy data to FIFOs, or setup DMA links. - When the interrupt transactions are used, an extra overhead is appended, - from the cost of FreeRTOS queues and the time switching between tasks and - the ISR. +- Transaction interval +- SPI clock frequency +- Cache miss of SPI functions, including callbacks - 1. For **interrupt transactions**, the CPU can switched to other - tasks when the transaction is in flight. This save the cpu time - but increase the interval (See :ref:`interrupt_transactions`). - For - **polling transactions**, it does not block the task but do - polling when the transaction is in flight. (See - :ref:`polling_transactions`). +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. - 2. When the DMA is enabled, it needs about 2us per transaction to setup the linked list. When the master is - transferring, it automatically read data from the linked list. If the DMA is not enabled, - CPU has to write/read each byte to/from the FIFO by itself. Usually this is faster than 2us, but the - transaction length is limited to 64 bytes for both write and read. - Typical transaction interval with one byte data is as below: +Transaction Interval +^^^^^^^^^^^^^^^^^^^^ - +--------+----------------+--------------+ - | | Typical Transaction Time (us) | - +========+================+==============+ - | | Interrupt | Polling | - +--------+----------------+--------------+ - | DMA | 24 | 8 | - +--------+----------------+--------------+ - | No DMA | 22 | 7 | - +--------+----------------+--------------+ +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. - 2. SPI clock frequency: Each byte transferred takes 8 times of the clock period *8/fspi*. If the clock frequency is - too high, some functions may be limited to use. See :ref:`timing_considerations`. +Interrupt transactions allow appending extra overhead to accommodate the cost of FreeRTOS queues and the time needed for switching between tasks and the ISR. - 3. The cache miss: the default config puts only the ISR into the IRAM. - Other SPI related functions including the driver itself and the callback - may suffer from the cache miss and wait for some time while reading code - 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 this. +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 an interrupt transaction, the overall cost is *20+8n/Fspi[MHz]* [us] for n bytes tranferred -in one transaction. Hence the transferring speed is : *n/(20+8n/Fspi)*. Example of transferring speed under 8MHz -clock speed: +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 | ++--------+----------------+--------------+ + + +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`. + + +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. + +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. +-----------+----------------------+--------------------+------------+-------------+ | Frequency | Transaction Interval | Transaction Length | Total Time | Total Speed | | | | | | | -| (MHz) | (us) | (bytes) | (us) | (kBps) | +| (MHz) | (us) | (bytes) | (us) | (KBps) | +===========+======================+====================+============+=============+ | 8 | 25 | 1 | 26 | 38.5 | +-----------+----------------------+--------------------+------------+-------------+ @@ -371,129 +327,90 @@ clock speed: | 8 | 25 | 128 | 153 | 836.6 | +-----------+----------------------+--------------------+------------+-------------+ -When the length of transaction is short, the cost of transaction interval is really high. Please try to squash data -into one transaction if possible to get higher transfer speed. +When a transaction length is short, the cost of transaction interval is high. If possible, try to squash several short transactions into one transaction to achieve a higher transfer speed. + +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`. -BTW, 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 ``intr_flags`` member of :cpp:class:`spi_bus_config_t`. Then all the -transactions queued before the flash operations will be handled by the ISR -continuously during flash operation. Note that the callback of each devices, -and their callee functions, should be in the IRAM in this case, or your -callback will crash due to cache miss. .. _timing_considerations: -Timing considerations -^^^^^^^^^^^^^^^^^^^^^ +Timing Considerations +--------------------- -As shown in the figure below, there is a delay on the MISO signal after SCLK -launch edge and before it's latched by the internal register. As a result, -the MISO pin setup time is the limiting factor for SPI clock speed. When the -delay is too large, setup slack is < 0 and the setup timing requirement is -violated, leads to the failure of 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, and the setup timing requirement is violated, which results in the failure to perform the reading correctly. .. image:: /../_static/spi_miso.png + :scale: 40 % + :align: center -.. wavedrom don't support rendering pdflatex till now(1.3.1), so we use the png here +.. wavedrom does not support rendering pdflatex till now(1.3.1), so we use the png here .. image:: /../_static/miso_timing_waveform.png -The maximum frequency allowed is related to the *input delay* (maximum valid -time after SCLK on the MISO bus), as well as the usage of GPIO matrix. The -maximum frequency allowed is reduced to about 33~77% (related to existing -*input delay*) when the GPIO matrix is used. To work at higher frequency, you -have to use the IOMUX pins or the *dummy bit workaround*. You can get the -maximum reading frequency of the master by ``spi_get_freq_limit``. +The maximum allowed frequency is dependent on: + +- ``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 + +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 bit workaround:** We can insert dummy clocks (during which the host does not read data) before the read phase -actually begins. The slave still sees the dummy clocks and gives out data, but the host does not read until the read -phase. This compensates the lack of setup time of MISO required by the host, allowing the host reading at higher -frequency. +**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. -In the ideal case (the slave is so fast that the input delay is shorter than an apb clock, 12.5ns), the maximum -frequency host can read (or read and write) under different conditions is as below: +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: +-------------+-------------+------------+-----------------------------+ | Frequency Limit (MHz) | Dummy Bits | Comments | +-------------+-------------+ Used + + -| GPIO matrix | IOMUX pins | By Driver | | +| GPIO matrix | IO_MUX pins | By Driver | | +=============+=============+============+=============================+ | 26.6 | 80 | No | | +-------------+-------------+------------+-----------------------------+ -| 40 | -- | Yes | Half Duplex, no DMA allowed | +| 40 | -- | Yes | Half-duplex, no DMA allowed | +-------------+-------------+------------+-----------------------------+ -And if the host only writes, the *dummy bit workaround* is not used and the frequency limit is as below: +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. -+-------------------+------------------+ -| GPIO matrix (MHz) | IOMUX pins (MHz) | -+===================+==================+ -| 40 | 80 | -+-------------------+------------------+ +:cpp:member:`spi_device_interface_config_t::flags` -The spi master driver can work even if the *input delay* in the ``spi_device_interface_config_t`` is set to 0. -However, setting a accurate value helps to: (1) calculate the frequency limit in full duplex mode, and (2) compensate -the timing correctly by dummy bits in half duplex mode. You may find the maximum data valid time after the launch edge -of SPI clocks in the AC characteristics chapter of the device specifications, or measure the time on a oscilloscope or -logic analyzer. +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: -.. wavedrom don't support rendering pdflatex till now(1.3.1), so we use the png here +- Calculate the frequency limit for full-duplex transactions +- Compensate the timing correctly with dummy bits for half-duplex transactions -.. image:: /../_static/miso_timing_waveform_async.png +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. -As shown in the figure above, the input delay is usually: +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. - *[input delay] = [sample delay] + [slave output delay]* +Some typical delay values are shown in the following table. - 1. The sample delay is the maximum random delay due to the - asynchronization of SCLK and peripheral clock of the slave. It's usually - 1 slave peripheral clock if the clock is asynchronize with SCLK, or 0 if - the slave just use the SCLK to latch the SCLK and launch MISO data. e.g. - for ESP32 slaves, the delay is 12.5ns (1 apb clock), while it is reduced - to 0 if the slave is in the same chip as the master. ++----------------------------------------+------------------+ +| 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. | ++-----------------------------------------------------------+ - 2. The slave output delay is the time for the MOSI to be stable after the - launch edge. e.g. for ESP32 slaves, the output delay is 37.5ns (3 apb - clocks) when IOMUX pins in the slave is used, or 62.5ns (5 apb clocks) if - through the GPIO matrix. +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: -Some typical delays are shown in the following table: + *Freq limit [MHz] = 80 / (floor(MISO delay[ns]/12.5) + 1)* -+--------------------+------------------+ -| Device | Input delay (ns) | -+====================+==================+ -| Ideal device | 0 | -+--------------------+------------------+ -| ESP32 slave IOMUX* | 50 | -+--------------------+------------------+ -| ESP32 slave GPIO* | 75 | -+--------------------+------------------+ -| ESP32 slave is on an independent | -| chip, 12.5ns sample delay included. | -+---------------------------------------+ - -The MISO path delay(tv), consists of slave *input delay* and master *GPIO matrix delay*, finally determines the -frequency limit, above which the full duplex mode will not work, or dummy bits are used in the half duplex mode. The -frequency limit is: - - *Freq limit[MHz] = 80 / (floor(MISO delay[ns]/12.5) + 1)* - -The figure below shows the relations of frequency limit against the input delay. 2 extra apb clocks should be counted -into the MISO delay if the GPIO matrix in the master is used. +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. .. image:: /../_static/spi_master_freq_tv.png -Corresponding frequency limit for different devices with different *input delay* are shown in the following -table: +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) | +========+==================+======================+===================+ -| IOMUX | 0 | 0 | 80 | +| IO_MUX | 0 | 0 | 80 | + (0ns) +------------------+----------------------+-------------------+ | | 50 | 50 | 16 | + +------------------+----------------------+-------------------+ @@ -512,27 +429,27 @@ table: Known Issues ------------ -1. Half duplex mode is not compatible with DMA when both writing and reading phases exist. +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: - 1. use full-duplex mode instead. - 2. disable the DMA by setting the last parameter to 0 in bus initialization function just as below: + 1. Use full-duplex transactions instead. + 2. Disable DMA by setting the bus initialization function's last parameter to 0 as follows: ``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);`` - this may prohibit you from transmitting and receiving data longer than 64 bytes. - 3. try to use command and address field to replace the write phase. + This can prohibit you from transmitting and receiving data longer than 64 bytes. + 3. Try using the command and address fields to replace the write phase. -2. Full duplex mode is not compatible with the *dummy bit workaround*, hence the frequency is limited. See :ref:`dummy +2. Full-duplex transactions are not compatible with the *dummy bit workaround*, hence the frequency is limited. See :ref:`dummy bit speed-up workaround `. -3. ``cs_ena_pretrans`` is not compatible with command, address phases in full duplex mode. +3. ``cs_ena_pretrans`` is not compatible with the command and address phases of full-duplex transactions. Application Example ------------------- -Display graphics on the 320x240 LCD of WROVER-Kits: :example:`peripherals/spi_master`. +The code example for displaying graphics on an ESP32-WROVER-KIT's 320x240 LCD screen can be found in the :example:`peripherals/spi_master` directory of ESP-IDF examples. API Reference - SPI Common