1 // Copyright 2010-2020 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 #pragma once 16 17 #include "esp_types.h" 18 #include "soc/soc_caps.h" 19 #include "esp_osal/esp_osal.h" 20 21 #include "hal/spi_types.h" 22 #include "driver/spi_common.h" 23 #include "sdkconfig.h" 24 25 #ifdef __cplusplus 26 extern "C" 27 { 28 #endif 29 30 #if !SOC_SPI_SUPPORT_SLAVE_HD_VER2 && !CI_HEADER_CHECK 31 #error The SPI peripheral does not support this feature 32 #endif 33 34 /// Descriptor of data to send/receive 35 typedef struct { 36 uint8_t* data; ///< Buffer to send, must be DMA capable 37 size_t len; ///< Len of data to send/receive. For receiving the buffer length should be multiples of 4 bytes, otherwise the extra part will be truncated. 38 size_t trans_len; ///< For RX direction, it indicates the data actually received. For TX direction, it is meaningless. 39 void* arg; ///< Extra argument indiciating this data 40 } spi_slave_hd_data_t; 41 42 /// Information of SPI Slave HD event 43 typedef struct { 44 spi_event_t event; ///< Event type 45 spi_slave_hd_data_t* trans; ///< Corresponding transaction for SPI_EV_SEND and SPI_EV_RECV events 46 } spi_slave_hd_event_t; 47 48 /// Callback for SPI Slave HD 49 typedef bool (*slave_cb_t)(void* arg, spi_slave_hd_event_t* event, BaseType_t* awoken); 50 51 /// Channel of SPI Slave HD to do data transaction 52 typedef enum { 53 SPI_SLAVE_CHAN_TX = 0, ///< The output channel (RDDMA) 54 SPI_SLAVE_CHAN_RX = 1, ///< The input channel (WRDMA) 55 } spi_slave_chan_t; 56 57 /// Callback configuration structure for SPI Slave HD 58 typedef struct { 59 slave_cb_t cb_buffer_tx; ///< Callback when master reads from shared buffer 60 slave_cb_t cb_buffer_rx; ///< Callback when master writes to shared buffer 61 slave_cb_t cb_send_dma_ready; ///< Callback when TX data buffer is loaded to the hardware (DMA) 62 slave_cb_t cb_sent; ///< Callback when data are sent 63 slave_cb_t cb_recv_dma_ready; ///< Callback when RX data buffer is loaded to the hardware (DMA) 64 slave_cb_t cb_recv; ///< Callback when data are received 65 slave_cb_t cb_cmd9; ///< Callback when CMD9 received 66 slave_cb_t cb_cmdA; ///< Callback when CMDA received 67 void* arg; ///< Argument indicating this SPI Slave HD peripheral instance 68 } spi_slave_hd_callback_config_t; 69 70 71 //flags for ``spi_slave_hd_slot_config_t`` to use 72 #define SPI_SLAVE_HD_TXBIT_LSBFIRST (1<<0) ///< Transmit command/address/data LSB first instead of the default MSB first 73 #define SPI_SLAVE_HD_RXBIT_LSBFIRST (1<<1) ///< Receive data LSB first instead of the default MSB first 74 #define SPI_SLAVE_HD_BIT_LSBFIRST (SPI_SLAVE_HD_TXBIT_LSBFIRST|SPI_SLAVE_HD_RXBIT_LSBFIRST) ///< Transmit and receive LSB first 75 #define SPI_SLAVE_HD_APPEND_MODE (1<<2) ///< Adopt DMA append mode for transactions. In this mode, users can load(append) DMA descriptors without stopping the DMA 76 77 /// Configuration structure for the SPI Slave HD driver 78 typedef struct { 79 uint8_t mode; /**< SPI mode, representing a pair of (CPOL, CPHA) configuration: 80 - 0: (0, 0) 81 - 1: (0, 1) 82 - 2: (1, 0) 83 - 3: (1, 1) 84 */ 85 uint32_t spics_io_num; ///< CS GPIO pin for this device 86 uint32_t flags; ///< Bitwise OR of SPI_SLAVE_HD_* flags 87 uint32_t command_bits; ///< command field bits, multiples of 8 and at least 8. 88 uint32_t address_bits; ///< address field bits, multiples of 8 and at least 8. 89 uint32_t dummy_bits; ///< dummy field bits, multiples of 8 and at least 8. 90 uint32_t queue_size; ///< Transaction queue size. This sets how many transactions can be 'in the air' (queued using spi_slave_hd_queue_trans but not yet finished using spi_slave_hd_get_trans_result) at the same time 91 spi_dma_chan_t dma_chan; ///< DMA channel to used. 92 spi_slave_hd_callback_config_t cb_config; ///< Callback configuration 93 } spi_slave_hd_slot_config_t; 94 95 /** 96 * @brief Initialize the SPI Slave HD driver. 97 * 98 * @param host_id The host to use 99 * @param bus_config Bus configuration for the bus used 100 * @param config Configuration for the SPI Slave HD driver 101 * @return 102 * - ESP_OK: on success 103 * - ESP_ERR_INVALID_ARG: invalid argument given 104 * - ESP_ERR_INVALID_STATE: function called in invalid state, may be some resources are already in use 105 * - ESP_ERR_NOT_FOUND if there is no available DMA channel 106 * - ESP_ERR_NO_MEM: memory allocation failed 107 * - or other return value from `esp_intr_alloc` 108 */ 109 esp_err_t spi_slave_hd_init(spi_host_device_t host_id, const spi_bus_config_t *bus_config, 110 const spi_slave_hd_slot_config_t *config); 111 112 /** 113 * @brief Deinitialize the SPI Slave HD driver 114 * 115 * @param host_id The host to deinitialize the driver 116 * @return 117 * - ESP_OK: on success 118 * - ESP_ERR_INVALID_ARG: if the host_id is not correct 119 */ 120 esp_err_t spi_slave_hd_deinit(spi_host_device_t host_id); 121 122 /** 123 * @brief Queue transactions (segment mode) 124 * 125 * @param host_id Host to queue the transaction 126 * @param chan SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX 127 * @param trans Transaction descriptors 128 * @param timeout Timeout before the data is queued 129 * @return 130 * - ESP_OK: on success 131 * - ESP_ERR_INVALID_ARG: The input argument is invalid. Can be the following reason: 132 * - The buffer given is not DMA capable 133 * - The length of data is invalid (not larger than 0, or exceed the max transfer length) 134 * - The transaction direction is invalid 135 * - ESP_ERR_TIMEOUT: Cannot queue the data before timeout. Master is still processing previous transaction. 136 * - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under segment mode. 137 */ 138 esp_err_t spi_slave_hd_queue_trans(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t* trans, TickType_t timeout); 139 140 /** 141 * @brief Get the result of a data transaction (segment mode) 142 * 143 * @note This API should be called successfully the same times as the ``spi_slave_hd_queue_trans``. 144 * 145 * @param host_id Host to queue the transaction 146 * @param chan Channel to get the result, SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX 147 * @param[out] out_trans Pointer to the transaction descriptor (``spi_slave_hd_data_t``) passed to the driver before. Hardware has finished this transaction. Member ``trans_len`` indicates the actual number of bytes of received data, it's meaningless for TX. 148 * @param timeout Timeout before the result is got 149 * @return 150 * - ESP_OK: on success 151 * - ESP_ERR_INVALID_ARG: Function is not valid 152 * - ESP_ERR_TIMEOUT: There's no transaction done before timeout 153 * - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under segment mode. 154 */ 155 esp_err_t spi_slave_hd_get_trans_res(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t **out_trans, TickType_t timeout); 156 157 /** 158 * @brief Read the shared registers 159 * 160 * @param host_id Host to read the shared registers 161 * @param addr Address of register to read, 0 to ``SOC_SPI_MAXIMUM_BUFFER_SIZE-1`` 162 * @param[out] out_data Output buffer to store the read data 163 * @param len Length to read, not larger than ``SOC_SPI_MAXIMUM_BUFFER_SIZE-addr`` 164 */ 165 void spi_slave_hd_read_buffer(spi_host_device_t host_id, int addr, uint8_t *out_data, size_t len); 166 167 /** 168 * @brief Write the shared registers 169 * 170 * @param host_id Host to write the shared registers 171 * @param addr Address of register to write, 0 to ``SOC_SPI_MAXIMUM_BUFFER_SIZE-1`` 172 * @param data Buffer holding the data to write 173 * @param len Length to write, ``SOC_SPI_MAXIMUM_BUFFER_SIZE-addr`` 174 */ 175 void spi_slave_hd_write_buffer(spi_host_device_t host_id, int addr, uint8_t *data, size_t len); 176 177 /** 178 * @brief Load transactions (append mode) 179 * 180 * @note In this mode, user transaction descriptors will be appended to the DMA and the DMA will keep processing the data without stopping 181 * 182 * @param host_id Host to load transactions 183 * @param chan SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX 184 * @param trans Transaction descriptor 185 * @param timeout Timeout before the transaction is loaded 186 * @return 187 * - ESP_OK: on success 188 * - ESP_ERR_INVALID_ARG: The input argument is invalid. Can be the following reason: 189 * - The buffer given is not DMA capable 190 * - The length of data is invalid (not larger than 0, or exceed the max transfer length) 191 * - The transaction direction is invalid 192 * - ESP_ERR_TIMEOUT: Master is still processing previous transaction. There is no available transaction for slave to load 193 * - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under append mode. 194 */ 195 esp_err_t spi_slave_hd_append_trans(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t *trans, TickType_t timeout); 196 197 /** 198 * @brief Get the result of a data transaction (append mode) 199 * 200 * @note This API should be called the same times as the ``spi_slave_hd_append_trans`` 201 * 202 * @param host_id Host to load the transaction 203 * @param chan SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX 204 * @param[out] out_trans Pointer to the transaction descriptor (``spi_slave_hd_data_t``) passed to the driver before. Hardware has finished this transaction. Member ``trans_len`` indicates the actual number of bytes of received data, it's meaningless for TX. 205 * @param timeout Timeout before the result is got 206 * @return 207 * - ESP_OK: on success 208 * - ESP_ERR_INVALID_ARG: Function is not valid 209 * - ESP_ERR_TIMEOUT: There's no transaction done before timeout 210 * - ESP_ERR_INVALID_STATE: Function called in invalid state. This API should be called under append mode. 211 */ 212 esp_err_t spi_slave_hd_get_append_trans_res(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t **out_trans, TickType_t timeout); 213 214 #ifdef __cplusplus 215 } 216 #endif 217