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