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