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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 diff --git a/docs/en/api-reference/peripherals/spi_master.rst b/docs/en/api-reference/peripherals/spi_master.rst index 13084274f..5d0bb1e8d 100644 --- a/docs/en/api-reference/peripherals/spi_master.rst +++ b/docs/en/api-reference/peripherals/spi_master.rst @@ -1,256 +1,246 @@ -SPI Master driver +SPI Master Driver ================= -Overview --------- +SPI Master driver is a program that controls ESP32's SPI peripherals while they function as masters. -The ESP32 has four SPI peripheral devices, called SPI0, SPI1, HSPI and VSPI. SPI0 is entirely dedicated to -the flash cache the ESP32 uses to map the SPI flash device it is connected to into memory. SPI1 is -connected to the same hardware lines as SPI0 and is used to write to the flash chip. HSPI and VSPI -are free to use. SPI1, HSPI and VSPI all have three chip select lines, allowing them to drive up to -three SPI devices each as a master. -The spi_master driver -^^^^^^^^^^^^^^^^^^^^^ +Overview of ESP32's SPI peripherals +----------------------------------- -The spi_master driver allows easy communicating with SPI slave devices, even in a multithreaded environment. -It fully transparently handles DMA transfers to read and write data and automatically takes care of -multiplexing between different SPI slaves on the same master. +ESP32 integrates four SPI peripherals. -.. note:: - - **Notes about thread safety** - - The SPI driver API is thread safe when multiple SPI devices on the same bus are accessed from different tasks. However, the driver is not thread safe if the same SPI device is accessed from multiple tasks. - - In this case, it is recommended to either refactor your application so only a single task accesses each SPI device, or to add mutex locking around access of the shared device. +- SPI0 and SPI1 are used internally to access the ESP32's attached flash memory and thus are currently not open to users. They share one signal bus via an arbiter. +- 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. Terminology -^^^^^^^^^^^ +----------- -The spi_master driver uses the following terms: +The terms used in relation to the SPI master driver are given in the table below. -* Host: The SPI peripheral inside the ESP32 initiating the SPI transmissions. One of SPI, HSPI or VSPI. (For - now, only HSPI or VSPI are actually supported in the driver; it will support all 3 peripherals - somewhere in the future.) -* Bus: The SPI bus, common to all SPI devices connected to one host. In general the bus consists of the - miso, mosi, sclk and optionally quadwp and quadhd signals. The SPI slaves are connected to these - signals in parallel. +================= ========================================================================================= +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.) +**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*. +**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. +================= ========================================================================================= - - miso - Also known as q, this is the input of the serial stream into the ESP32 - - mosi - Also known as d, this is the output of the serial stream from the ESP32 +Driver Features +--------------- - - sclk - Clock signal. Each data bit is clocked out or in on the positive or negative edge of this signal +The SPI master driver governs communications of Hosts with Devices. The driver supports the following features: - - quadwp - Write Protect signal. Only used for 4-bit (qio/qout) transactions. +- Multi-threaded environments +- Transparent handling of DMA transfers while reading and writing data +- Automatic time-division multiplexing of data coming from different Devices on the same signal bus - - quadhd - Hold signal. Only used for 4-bit (qio/qout) transactions. +.. warning:: -* Device: A SPI slave. Each SPI slave has its own chip select (CS) line, which is made active when - a transmission to/from the SPI slave occurs. -* Transaction: One instance of CS going active, data transfer from and/or to a device happening, and - CS going inactive again. Transactions are atomic, as in they will never be interrupted by another - transaction. + The SPI master driver has the concept of multiple Devices connected to a single bus (sharing a single ESP32 SPI peripheral). As long as each Device is accessed by only one task, the driver is thread safe. However, if multiple tasks try to access the same SPI Device, the driver is **not thread-safe**. In this case, it is recommended to either: -SPI transactions -^^^^^^^^^^^^^^^^ + - Refactor your application so that each SPI peripheral is only accessed by a single task at a time. + - Add a mutex lock around the shared Device using :c:macro:`xSemaphoreCreateMutex`. -A transaction on the SPI bus consists of five phases, any of which may be skipped: -* The command phase. In this phase, a command (0-16 bit) is clocked out. -* The address phase. In this phase, an address (0-64 bit) is clocked out. -* The write phase. The master sends data to the slave. -* The dummy phase. The phase is configurable, used to meet the timing requirements. -* The read phase. The slave sends data to the master. +SPI Transactions +---------------- -In full duplex mode, the read and write phases are combined, and the SPI host reads and -writes data simultaneously. The total transaction length is decided by -``command_bits + address_bits + trans_conf.length``, while the ``trans_conf.rx_length`` -only determins length of data received into the buffer. +An SPI bus transaction consists of five phases which can be found in the table below. Any of these phases can be skipped. -While in half duplex mode, the host have independent write and read phases. The length of write phase and read phase are -decided by ``trans_conf.length`` and ``trans_conf.rx_length`` respectively. +============== ========================================================================================================= +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. +**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. +============== ========================================================================================================= -The command and address phase are optional in that not every SPI device will need to be sent a command -and/or address. This is reflected in the device configuration: when the ``command_bits`` or ``address_bits`` -fields are set to zero, no command or address phase is done. +.. todo:: -Something similar is true for the read and write phase: not every transaction needs both data to be written -as well as data to be read. When ``rx_buffer`` is NULL (and SPI_TRANS_USE_RXDATA) is not set) the read phase -is skipped. When ``tx_buffer`` is NULL (and SPI_TRANS_USE_TXDATA) is not set) the write phase is skipped. + Add a package diagram. + + +The attributes of a transaction are determined by the bus configuration structure :cpp:type:`spi_bus_config_t`, device configuration structure :cpp:type:`spi_device_interface_config_t`, and transaction configuration structure :cpp:type:`spi_transaction_t`. + +An SPI Host can send full-duplex transactions, during which the read and write phases occur simultaneously. The total transaction length is determined by the sum of the following members: + +- :cpp:member:`spi_device_interface_config_t::command_bits` +- :cpp:member:`spi_device_interface_config_t::address_bits` +- :cpp:member:`spi_transaction_t::length` + +While the member :cpp:member:`spi_transaction_t::rxlength` only determines the length of data received into the buffer. + +In half-duplex transactions, the read and write phases are not simultaneous (one direction at a time). The lengths of the write and read phases are determined by :cpp:member:`length` and :cpp:member:`rxlength` members of the struct :cpp:type:`spi_transaction_t` respectively. + +The command and address phases are optional, as not every SPI device requires a command and/or address. This is reflected in the Device's configuration: if :cpp:member:`command_bits` and/or :cpp:member:`address_bits` are set to zero, no command or address phase will occur. + +The read and write phases can also be optional, as not every transaction requires both writing and reading data. If :cpp:member:`rx_buffer` is NULL and :cpp:type:`SPI_TRANS_USE_RXDATA` is not set, the read phase is skipped. If :cpp:member:`tx_buffer` is NULL and :cpp:type:`SPI_TRANS_USE_TXDATA` is not set, the write phase is skipped. + +The driver supports two types of transactions: the interrupt transactions and polling transactions. The programmer can choose to use a different transaction type per Device. If your Device requires both transaction types, see :ref:`mixed_transactions`. -The driver offers two different kinds of transactions: the interrupt -transactions and the polling transactions. Each device can choose one kind of -transaction to send. See :ref:`mixed_transactions` if your device do require -both kinds of transactions. .. _interrupt_transactions: -Interrupt transactions -"""""""""""""""""""""""" +Interrupt Transactions +^^^^^^^^^^^^^^^^^^^^^^ -The interrupt transactions use an interrupt-driven logic when the -transactions are in-flight. The routine will get blocked, allowing the CPU to -run other tasks, while it is waiting for a transaction to be finished. +Interrupt transactions will block the transaction routine until the transaction completes, thus allowing the CPU to run other tasks. + +An application task can queue multiple transactions, and the driver will automatically handle them one-by-one in the interrupt service routine (ISR). It allows the task to switch to other procedures until all the transactions complete. -Interrupt transactions can be queued into a device, the driver automatically -send them one-by-one in the ISR. A task can queue several transactions, and -then do something else before the transactions are finished. .. _polling_transactions: -Polling transactions -"""""""""""""""""""" +Polling Transactions +^^^^^^^^^^^^^^^^^^^^ -The polling transactions don't rely on the interrupt, the routine keeps polling -the status bit of the SPI peripheral until the transaction is done. +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 do interrupt transactions may get blocked by the queue, at -which point they need to wait for the ISR to run twice before the transaction -is done. Polling transactions save the time spent on queue handling and -context switching, resulting in a smaller transaction interval smaller. The -disadvantage is that the the CPU is busy while these transactions are in -flight. +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. -The ``spi_device_polling_end`` routine spends at least 1us overhead to -unblock other tasks when the transaction is done. It is strongly recommended -to wrap a series of polling transactions inside of ``spi_device_acquire_bus`` -and ``spi_device_release_bus`` to avoid the overhead. (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`. -Command and address phases + +Command and Address Phases ^^^^^^^^^^^^^^^^^^^^^^^^^^ -During the command and address phases, ``cmd`` and ``addr`` field in the -``spi_transaction_t`` struct are sent to the bus, while nothing is read at the -same time. The default length of command and address phase are set in the -``spi_device_interface_config_t`` and by ``spi_bus_add_device``. When the the -flag ``SPI_TRANS_VARIABLE_CMD`` and ``SPI_TRANS_VARIABLE_ADDR`` are not set in -the ``spi_transaction_t``,the driver automatically set the length of these -phases to the default value as set when the device is initialized respectively. +During the command and address phases, the members :cpp:member:`cmd` and :cpp:member:`addr` in the struct :cpp:type:`spi_transaction_t` are sent to the bus, nothing is read at this time. The default lengths of the command and address phases are set in :cpp:type:`spi_device_interface_config_t` by calling :cpp:func:`spi_bus_add_device`. If the flags :cpp:type:`SPI_TRANS_VARIABLE_CMD` and :cpp:type:`SPI_TRANS_VARIABLE_ADDR` in the member :cpp:member:`spi_transaction_t::flags` are not set, the driver automatically sets the length of these phases to default values during Device initialization. -If the length of command and address phases needs to be variable, declare a -``spi_transaction_ext_t`` descriptor, set the flag ``SPI_TRANS_VARIABLE_CMD`` -or/and ``SPI_TRANS_VARIABLE_ADDR`` in the ``flags`` of ``base`` member and -configure the rest part of ``base`` as usual. Then the length of each phases -will be ``command_bits`` and ``address_bits`` set in the ``spi_transaction_ext_t``. +If the lengths of the command and address phases need to be variable, declare the struct :cpp:type:`spi_transaction_ext_t`, set the flags :cpp:type:`SPI_TRANS_VARIABLE_CMD` and/or :cpp:type:`SPI_TRANS_VARIABLE_ADDR` in the member :cpp:member:`spi_transaction_ext_t::base` and configure the rest of base as usual. Then the length of each phase will be equal to :cpp:member:`command_bits` and :cpp:member:`address_bits` set in the struct :cpp:type:`spi_transaction_ext_t`. -Write and read phases + +Write and Read Phases ^^^^^^^^^^^^^^^^^^^^^ -Normally, data to be transferred to or from a device will be read from or written to a chunk of memory -indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. -When DMA is enabled for transfers, these buffers are highly recommended to meet the requirements as below: +Normally, the data that needs to be transferred to or from a Device will be read from or written to a chunk of memory indicated by the members :cpp:member:`rx_buffer` and :cpp:member:`tx_buffer` of the structure :cpp:type:`spi_transaction_t`. If DMA is enabled for transfers, the buffers are required to be: - 1. allocated in DMA-capable memory using ``pvPortMallocCaps(size, MALLOC_CAP_DMA)``; - 2. 32-bit aligned (start from the boundary and have length of multiples of 4 bytes). + 1. Allocated in DMA-capable internal memory. If :ref:`external PSRAM is enabled`, 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