1 /* 2 * SPDX-FileCopyrightText: 2010-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 8 #ifndef _DRIVER_SPI_SLAVE_H_ 9 #define _DRIVER_SPI_SLAVE_H_ 10 11 #include "esp_err.h" 12 #include "freertos/FreeRTOS.h" 13 #include "freertos/semphr.h" 14 #include "driver/spi_common.h" 15 16 17 #ifdef __cplusplus 18 extern "C" 19 { 20 #endif 21 22 23 #define SPI_SLAVE_TXBIT_LSBFIRST (1<<0) ///< Transmit command/address/data LSB first instead of the default MSB first 24 #define SPI_SLAVE_RXBIT_LSBFIRST (1<<1) ///< Receive data LSB first instead of the default MSB first 25 #define SPI_SLAVE_BIT_LSBFIRST (SPI_SLAVE_TXBIT_LSBFIRST|SPI_SLAVE_RXBIT_LSBFIRST) ///< Transmit and receive LSB first 26 27 28 typedef struct spi_slave_transaction_t spi_slave_transaction_t; 29 typedef void(*slave_transaction_cb_t)(spi_slave_transaction_t *trans); 30 31 /** 32 * @brief This is a configuration for a SPI host acting as a slave device. 33 */ 34 typedef struct { 35 int spics_io_num; ///< CS GPIO pin for this device 36 uint32_t flags; ///< Bitwise OR of SPI_SLAVE_* flags 37 int queue_size; ///< Transaction queue size. This sets how many transactions can be 'in the air' (queued using spi_slave_queue_trans but not yet finished using spi_slave_get_trans_result) at the same time 38 uint8_t mode; /**< SPI mode, representing a pair of (CPOL, CPHA) configuration: 39 - 0: (0, 0) 40 - 1: (0, 1) 41 - 2: (1, 0) 42 - 3: (1, 1) 43 */ 44 slave_transaction_cb_t post_setup_cb; /**< Callback called after the SPI registers are loaded with new data. 45 * 46 * This callback is called within interrupt 47 * context should be in IRAM for best 48 * performance, see "Transferring Speed" 49 * section in the SPI Master documentation for 50 * full details. If not, the callback may crash 51 * during flash operation when the driver is 52 * initialized with ESP_INTR_FLAG_IRAM. 53 */ 54 slave_transaction_cb_t post_trans_cb; /**< Callback called after a transaction is done. 55 * 56 * This callback is called within interrupt 57 * context should be in IRAM for best 58 * performance, see "Transferring Speed" 59 * section in the SPI Master documentation for 60 * full details. If not, the callback may crash 61 * during flash operation when the driver is 62 * initialized with ESP_INTR_FLAG_IRAM. 63 */ 64 } spi_slave_interface_config_t; 65 66 /** 67 * This structure describes one SPI transaction 68 */ 69 struct spi_slave_transaction_t { 70 size_t length; ///< Total data length, in bits 71 size_t trans_len; ///< Transaction data length, in bits 72 const void *tx_buffer; ///< Pointer to transmit buffer, or NULL for no MOSI phase 73 void *rx_buffer; /**< Pointer to receive buffer, or NULL for no MISO phase. 74 * When the DMA is anabled, must start at WORD boundary (``rx_buffer%4==0``), 75 * and has length of a multiple of 4 bytes. 76 */ 77 void *user; ///< User-defined variable. Can be used to store eg transaction ID. 78 }; 79 80 /** 81 * @brief Initialize a SPI bus as a slave interface 82 * 83 * @warning SPI0/1 is not supported 84 * 85 * @param host SPI peripheral to use as a SPI slave interface 86 * @param bus_config Pointer to a spi_bus_config_t struct specifying how the host should be initialized 87 * @param slave_config Pointer to a spi_slave_interface_config_t struct specifying the details for the slave interface 88 * @param 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. 89 * - Selecting SPI_DMA_DISABLED limits the size of transactions. 90 * - Set to SPI_DMA_DISABLED if only the SPI flash uses this bus. 91 * - Set to SPI_DMA_CH_AUTO to let the driver to allocate the DMA channel. 92 * 93 * @warning If a DMA channel is selected, any transmit and receive buffer used should be allocated in 94 * DMA-capable memory. 95 * 96 * @warning The ISR of SPI is always executed on the core which calls this 97 * function. Never starve the ISR on this core or the SPI transactions will not 98 * be handled. 99 * 100 * @return 101 * - ESP_ERR_INVALID_ARG if configuration is invalid 102 * - ESP_ERR_INVALID_STATE if host already is in use 103 * - ESP_ERR_NOT_FOUND if there is no available DMA channel 104 * - ESP_ERR_NO_MEM if out of memory 105 * - ESP_OK on success 106 */ 107 esp_err_t spi_slave_initialize(spi_host_device_t host, const spi_bus_config_t *bus_config, const spi_slave_interface_config_t *slave_config, spi_dma_chan_t dma_chan); 108 109 /** 110 * @brief Free a SPI bus claimed as a SPI slave interface 111 * 112 * @param host SPI peripheral to free 113 * @return 114 * - ESP_ERR_INVALID_ARG if parameter is invalid 115 * - ESP_ERR_INVALID_STATE if not all devices on the bus are freed 116 * - ESP_OK on success 117 */ 118 esp_err_t spi_slave_free(spi_host_device_t host); 119 120 121 /** 122 * @brief Queue a SPI transaction for execution 123 * 124 * Queues a SPI transaction to be executed by this slave device. (The transaction queue size was specified when the slave 125 * device was initialised via spi_slave_initialize.) This function may block if the queue is full (depending on the 126 * ticks_to_wait parameter). No SPI operation is directly initiated by this function, the next queued transaction 127 * will happen when the master initiates a SPI transaction by pulling down CS and sending out clock signals. 128 * 129 * This function hands over ownership of the buffers in ``trans_desc`` to the SPI slave driver; the application is 130 * not to access this memory until ``spi_slave_queue_trans`` is called to hand ownership back to the application. 131 * 132 * @param host SPI peripheral that is acting as a slave 133 * @param trans_desc Description of transaction to execute. Not const because we may want to write status back 134 * into the transaction description. 135 * @param ticks_to_wait Ticks to wait until there's room in the queue; use portMAX_DELAY to 136 * never time out. 137 * @return 138 * - ESP_ERR_INVALID_ARG if parameter is invalid 139 * - ESP_OK on success 140 */ 141 esp_err_t spi_slave_queue_trans(spi_host_device_t host, const spi_slave_transaction_t *trans_desc, TickType_t ticks_to_wait); 142 143 144 /** 145 * @brief Get the result of a SPI transaction queued earlier 146 * 147 * This routine will wait until a transaction to the given device (queued earlier with 148 * spi_slave_queue_trans) has succesfully completed. It will then return the description of the 149 * completed transaction so software can inspect the result and e.g. free the memory or 150 * re-use the buffers. 151 * 152 * It is mandatory to eventually use this function for any transaction queued by ``spi_slave_queue_trans``. 153 * 154 * @param host SPI peripheral to that is acting as a slave 155 * @param[out] trans_desc Pointer to variable able to contain a pointer to the description of the 156 * transaction that is executed 157 * @param ticks_to_wait Ticks to wait until there's a returned item; use portMAX_DELAY to never time 158 * out. 159 * @return 160 * - ESP_ERR_INVALID_ARG if parameter is invalid 161 * - ESP_OK on success 162 */ 163 esp_err_t spi_slave_get_trans_result(spi_host_device_t host, spi_slave_transaction_t **trans_desc, TickType_t ticks_to_wait); 164 165 166 /** 167 * @brief Do a SPI transaction 168 * 169 * Essentially does the same as spi_slave_queue_trans followed by spi_slave_get_trans_result. Do 170 * not use this when there is still a transaction queued that hasn't been finalized 171 * using spi_slave_get_trans_result. 172 * 173 * @param host SPI peripheral to that is acting as a slave 174 * @param trans_desc Pointer to variable able to contain a pointer to the description of the 175 * transaction that is executed. Not const because we may want to write status back 176 * into the transaction description. 177 * @param ticks_to_wait Ticks to wait until there's a returned item; use portMAX_DELAY to never time 178 * out. 179 * @return 180 * - ESP_ERR_INVALID_ARG if parameter is invalid 181 * - ESP_OK on success 182 */ 183 esp_err_t spi_slave_transmit(spi_host_device_t host, spi_slave_transaction_t *trans_desc, TickType_t ticks_to_wait); 184 185 186 #ifdef __cplusplus 187 } 188 #endif 189 190 #endif 191
