Espressif ESP32-S2 User Manual

Chapter 2. API Reference
Deinitialization (optional) Call spi_slave_hd_deinit() to uninstall the driver. The resources, including
the pins, SPI peripheral, internal memory used by the driver, interrupt sources, will be released by the deinit function.
Send/Receive Data by DMA Channels To send data to the master through the sending DMA channel,
the application should properly wrap the data to send by a spi_slave_hd_data_t descriptor struc-
ture before calling spi_slave_hd_queue_trans() with the data descriptor, and the channel argu-
ment of SPI_SLAVE_CHAN_TX. The pointers to descriptors are stored in the queue, and the data will be
send to the master upon master’s RDDMA command in the same order they are put into the queue by
spi_slave_hd_queue_trans().
The application should check the result of data sending by calling spi_slave_hd_get_trans_res() with
the channel set as SPI_SLAVE_CHAN_TX. This function will block until the transaction with command RDDMA
from master successfully completes (or timeout). The out_trans argument of the function will output the pointer
of the data descriptor which is just finished.
Receiving data from the master through the receiving DMA channel is quite similar. The applica-
tion calls spi_slave_hd_queue_trans() with proper data descriptor and the channel argument of
SPI_SLAVE_CHAN_RX. And the application calls the spi_slave_hd_get_trans_res() later to get the
descriptor to the receiving buffer, before it handles the data in the receiving buffer.
Note: This driver itself doesn’t have internal buffer for the data to send, or just received. The application should
provide data descriptors for the data buffer to send to master, or to receive data from the master.
The application will have to properly keep the data descriptor as well as the buffer it points to, after the descriptor
is successfully sent into the driver internal queue by spi_slave_hd_queue_trans(), and before returned by
spi_slave_hd_get_trans_res(). During this period, the hardware as well as the driver may read or write
to the buffer and the descriptor when required at any time.
Please note that the buffer doesn’t have to be fully sent or filled before it’s terminated. For example, in the segment
transaction mode, the master has to send CMD7 to terminate a WRDMA transaction, or send CMD8 to terminate a
RDDMA transaction (in segments), no matter the send (receive) buffer is used up (full) or not.
Using Data Arguments Sometimes you may have initiator (sending data descriptor) and closure (handling returned
descriptors) functions in different places. When you get the returned data descriptor in the closure, you may need
some extra information when handle the finished data descriptor. For example, you may want to know which round
it is for the returned descriptor, when you send the same piece of data for several times.
Set the arg member in the data descriptor to an variable indicating the transaction (by force casting), or point it to
a a structure which wraps all the information you may need when handling the sending/receiving data. Then you can
get what you need in your closure.
Using callbacks
Note: These callbacks are called in the ISR, so that they are fast enough. However, you may need to be very careful
to write the code in the ISR. The callback should return as soon as possible. No delay or blocking operations are
allowed.
The spi_slave_hd_intr_config_t member in the spi_slave_hd_slot_config_t configuration
structure passed when initialize the SPI Slave HD driver, allows you having callbacks for each events you may concern.
The corresponding interrupt for each callbacks that is not NULL will enabled, so that the callbacks can be called
immediately when the events happen. You don’t need to provide callbacks for the unconcerned events.
The arg member in the configuration structure can help you pass some context to the callback, or indicate which
SPI Slave instance when you are using the same callbacks for several SPI Slave peripherals. Set the arg member to
an variable indicating the SPI Slave instance (by force casting), or point it to a context structure. All the callbacks
will be called with this arg argument you set when the callbacks are initialized.
Espressif Systems 389
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English