Chapter 2. API Reference
The attributes of a transaction are determined by the configuration structure for an SPI host act-
ing as a slave device spi_slave_interface_config_t, and transaction configuration structure
spi_slave_transaction_t.
As not every transaction requires both writing and reading data, you have a choice to config-
ure the spi_transaction_t structure for TX only, RX only, or TX and RX transactions. If
spi_slave_transaction_t::rx_buffer is set to NULL, the read phase will be skipped. If
spi_slave_transaction_t::tx_buffer is set to NULL, the write phase will be skipped.
Note: A Host should not start a transaction before its Device is ready for receiving data. It is recommended to use
another GPIO pin for a handshake signal to sync the Devices. For more details, see Transaction Interval.
Driver Usage
• Initialize an SPI peripheral as a Device by calling the function cpp:func:spi_slave_initialize. Make sure to set
the correct I/O pins in the struct bus_config. Set the unused signals to -1.
If transactions will be longer than 32 bytes, allow a DMA channel by setting the parameter dma_chan to the host
device. Otherwise, set dma_chan to 0.
• Before initiating transactions, fill one or more spi_slave_transaction_t structs with the transaction
parameters required. Either queue all transactions by calling the function spi_slave_queue_trans()
and, at a later time, query the result by using the function spi_slave_get_trans_result(), or handle
all requests individually by feeding them into spi_slave_transmit(). The latter two functions will be
blocked until the Host has initiated and finished a transaction, causing the queued data to be sent and received.
• (Optional) To unload the SPI slave driver, call spi_slave_free().
Transaction Data and Master/Slave Length Mismatches
Normally, the data that needs to be transferred to or from a Device is read or written to a chunk of memory indicated
by the rx_buffer and tx_buffer members of the spi_transaction_t structure. The SPI driver can be
configured to use DMA for transfers, in which case these buffers must be allocated in DMA-capable memory using
pvPortMallocCaps(size, MALLOC_CAP_DMA).
The amount of data that the driver can read or write to the buffers is limited by the member
spi_transaction_t::length. However, this member does not define the actual length of an SPI
transaction. A transaction’s length is determined by a Host which drives the clock and CS lines.
The actual length of the transmission can be read only after a transaction is finished from the member
spi_slave_transaction_t::trans_len.
If the length of the transmission is greater than the buffer length, only the initial number of bits specified in the
length member will be sent and received. In this case, trans_len is set to length instead of the actual
transaction length. To meet the actual transaction length requirements, set length to a value greater than the
maximum trans_len expected. If the transmission length is shorter than the buffer length, only the data equal to
the length of the buffer will be transmitted.
Speed and Timing Considerations
Transaction Interval The ESP32-S2 SPI slave peripherals are designed as general purpose Devices controlled by
a CPU. As opposed to dedicated slaves, CPU-based SPI Devices have a limited number of pre-defined registers. All
transactions must be handled by the CPU, which means that the transfers and responses are not real-time, and there
might be noticeable latency.
As a solution, a Device’s response rate can be doubled by using the functions spi_slave_queue_trans()
and then spi_slave_get_trans_result() instead of using spi_slave_transmit().
You can also configure a GPIO pin through which the Device will signal to the Host when it is ready for a new
transaction. A code example of this can be found in peripherals/spi_slave.
Espressif Systems 384
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General