Chapter 2. API Reference
Functions
esp_err_t spi_bus_initialize(spi_host_device_t host_id, const spi_bus_config_t *bus_config,
spi_dma_chan_t dma_chan)
Initialize a SPI bus.
Warning SPI0/1 is not supported
Warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in DMA-
capable memory.
Warning The ISR of SPI is always executed on the core which calls this function. Never starve the ISR on
this core or the SPI transactions will not be handled.
Return
• ESP_ERR_INVALID_ARG if configuration is invalid
• ESP_ERR_INVALID_STATE if host already is in use
• ESP_ERR_NOT_FOUND if there is no available DMA channel
• ESP_ERR_NO_MEM if out of memory
• ESP_OK on success
Parameters
• host_id: SPI peripheral that controls this bus
• bus_config: Pointer to a spi_bus_config_t struct specifying how the host should be initialized
• dma_chan: - Selecting a DMA channel for an SPI bus allows transactions on the bus with size only
limited by the amount of internal memory.
– Selecting SPI_DMA_DISABLED limits the size of transactions.
– Set to SPI_DMA_DISABLED if only the SPI flash uses this bus.
– Set to SPI_DMA_CH_AUTO to let the driver to allocate the DMA channel.
esp_err_t spi_bus_free(spi_host_device_t host_id)
Free a SPI bus.
Warning In order for this to succeed, all devices have to be removed first.
Return
• ESP_ERR_INVALID_ARG if parameter is invalid
• ESP_ERR_INVALID_STATE if not all devices on the bus are freed
• ESP_OK on success
Parameters
• host_id: SPI peripheral to free
Structures
struct spi_bus_config_t
This is a configuration structure for a SPI bus.
You can use this structure to specify the GPIO pins of the bus. Normally, the driver will use the GPIO matrix
to route the signals. An exception is made when all signals either can be routed through the IO_MUX or are
-1. In that case, the IO_MUX is used, allowing for >40MHz speeds.
Note Be advised that the slave driver does not use the quadwp/quadhd lines and fields in spi_bus_config_t
refering to these lines will be ignored and can thus safely be left uninitialized.
Public Members
int mosi_io_num
GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.
int data0_io_num
GPIO pin for spi data0 signal in quad/octal mode, or -1 if not used.
int miso_io_num
GPIO pin for Master In Slave Out (=spi_q) signal, or -1 if not used.
int data1_io_num
GPIO pin for spi data1 signal in quad/octal mode, or -1 if not used.
Espressif Systems 372
Submit Document Feedback
Release v4.4