1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef R_SPI_API_H 8 #define R_SPI_API_H 9 10 /*****************************************************************************************************************//** 11 * @ingroup RENESAS_CONNECTIVITY_INTERFACES 12 * @defgroup SPI_API SPI Interface 13 * @brief Interface for SPI communications. 14 * 15 * @section SPI_API_SUMMARY Summary 16 * Provides a common interface for communication using the SPI Protocol. 17 * 18 * 19 * @{ 20 ********************************************************************************************************************/ 21 22 /********************************************************************************************************************* 23 * Includes 24 ********************************************************************************************************************/ 25 26 /* Includes board and MCU related header files. */ 27 #include "bsp_api.h" 28 #include "r_transfer_api.h" 29 30 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 31 FSP_HEADER 32 33 /********************************************************************************************************************* 34 * Macro definitions 35 ********************************************************************************************************************/ 36 37 /********************************************************************************************************************* 38 * Typedef definitions 39 ********************************************************************************************************************/ 40 41 #ifndef BSP_OVERRIDE_SPI_BIT_WIDTH_T 42 43 /** Data bit width */ 44 typedef enum e_spi_bit_width 45 { 46 SPI_BIT_WIDTH_4_BITS = (3), ///< Data bit width is 4 bits 47 SPI_BIT_WIDTH_5_BITS = (4), ///< Data bit width is 5 bits 48 SPI_BIT_WIDTH_6_BITS = (5), ///< Data bit width is 6 bits 49 SPI_BIT_WIDTH_7_BITS = (6), ///< Data bit width is 7 bits 50 SPI_BIT_WIDTH_8_BITS = (7), ///< Data bit width is 8 bits 51 SPI_BIT_WIDTH_9_BITS = (8), ///< Data bit width is 9 bits 52 SPI_BIT_WIDTH_10_BITS = (9), ///< Data bit width is 10 bits 53 SPI_BIT_WIDTH_11_BITS = (10), ///< Data bit width is 11 bits 54 SPI_BIT_WIDTH_12_BITS = (11), ///< Data bit width is 12 bits 55 SPI_BIT_WIDTH_13_BITS = (12), ///< Data bit width is 13 bits 56 SPI_BIT_WIDTH_14_BITS = (13), ///< Data bit width is 14 bits 57 SPI_BIT_WIDTH_15_BITS = (14), ///< Data bit width is 15 bits 58 SPI_BIT_WIDTH_16_BITS = (15), ///< Data bit width is 16 bits 59 SPI_BIT_WIDTH_17_BITS = (16), ///< Data bit width is 17 bits 60 SPI_BIT_WIDTH_18_BITS = (17), ///< Data bit width is 18 bits 61 SPI_BIT_WIDTH_19_BITS = (18), ///< Data bit width is 19 bits 62 SPI_BIT_WIDTH_20_BITS = (19), ///< Data bit width is 20 bits 63 SPI_BIT_WIDTH_21_BITS = (20), ///< Data bit width is 21 bits 64 SPI_BIT_WIDTH_22_BITS = (21), ///< Data bit width is 22 bits 65 SPI_BIT_WIDTH_23_BITS = (22), ///< Data bit width is 23 bits 66 SPI_BIT_WIDTH_24_BITS = (23), ///< Data bit width is 24 bits 67 SPI_BIT_WIDTH_25_BITS = (24), ///< Data bit width is 25 bits 68 SPI_BIT_WIDTH_26_BITS = (25), ///< Data bit width is 26 bits 69 SPI_BIT_WIDTH_27_BITS = (26), ///< Data bit width is 27 bits 70 SPI_BIT_WIDTH_28_BITS = (27), ///< Data bit width is 28 bits 71 SPI_BIT_WIDTH_29_BITS = (28), ///< Data bit width is 29 bits 72 SPI_BIT_WIDTH_30_BITS = (29), ///< Data bit width is 30 bits 73 SPI_BIT_WIDTH_31_BITS = (30), ///< Data bit width is 31 bits 74 SPI_BIT_WIDTH_32_BITS = (31) ///< Data bit width is 32 bits 75 } spi_bit_width_t; 76 #endif 77 78 #ifndef BSP_OVERRIDE_SPI_MODE_T 79 80 /** Master or slave operating mode */ 81 typedef enum e_spi_mode 82 { 83 SPI_MODE_MASTER, ///< Channel operates as SPI master 84 SPI_MODE_SLAVE ///< Channel operates as SPI slave 85 } spi_mode_t; 86 #endif 87 88 #ifndef BSP_OVERRIDE_SPI_CLK_PHASE_T 89 90 /** Clock phase */ 91 typedef enum e_spi_clk_phase 92 { 93 SPI_CLK_PHASE_EDGE_ODD, ///< 0: Data sampling on odd edge, data variation on even edge 94 SPI_CLK_PHASE_EDGE_EVEN ///< 1: Data variation on odd edge, data sampling on even edge 95 } spi_clk_phase_t; 96 #endif 97 98 #ifndef BSP_OVERRIDE_SPI_CLK_POLARITY_T 99 100 /** Clock polarity */ 101 typedef enum e_spi_clk_polarity 102 { 103 SPI_CLK_POLARITY_LOW, ///< 0: Clock polarity is low when idle 104 SPI_CLK_POLARITY_HIGH ///< 1: Clock polarity is high when idle 105 } spi_clk_polarity_t; 106 #endif 107 108 /** Mode fault error flag. This error occurs when the device is setup as a master, but the SSLA line does not seem to be 109 * controlled by the master. This usually happens when the connecting device is also acting as master. 110 * A similar situation can also happen when configured as a slave. */ 111 typedef enum e_spi_mode_fault 112 { 113 SPI_MODE_FAULT_ERROR_ENABLE, ///< Mode fault error flag on 114 SPI_MODE_FAULT_ERROR_DISABLE ///< Mode fault error flag off 115 } spi_mode_fault_t; 116 117 #ifndef BSP_OVERRIDE_SPI_BIT_ORDER_T 118 119 /** Bit order */ 120 typedef enum e_spi_bit_order 121 { 122 SPI_BIT_ORDER_MSB_FIRST, ///< Send MSB first in transmission 123 SPI_BIT_ORDER_LSB_FIRST ///< Send LSB first in transmission 124 } spi_bit_order_t; 125 #endif 126 127 /** SPI events */ 128 typedef enum e_spi_event 129 { 130 SPI_EVENT_TRANSFER_COMPLETE = 1, ///< The data transfer was completed 131 SPI_EVENT_TRANSFER_ABORTED, ///< The data transfer was aborted 132 SPI_EVENT_ERR_MODE_FAULT, ///< Mode fault error 133 SPI_EVENT_ERR_READ_OVERFLOW, ///< Read overflow error 134 SPI_EVENT_ERR_PARITY, ///< Parity error 135 SPI_EVENT_ERR_OVERRUN, ///< Overrun error 136 SPI_EVENT_ERR_FRAMING, ///< Framing error 137 SPI_EVENT_ERR_MODE_UNDERRUN ///< Underrun error 138 } spi_event_t; 139 140 /** Common callback parameter definition */ 141 typedef struct st_spi_callback_args 142 { 143 uint32_t channel; ///< Device channel number 144 spi_event_t event; ///< Event code 145 void const * p_context; ///< Context provided to user during callback 146 } spi_callback_args_t; 147 148 /** Non-secure arguments for write-read guard function */ 149 typedef struct st_spi_write_read_guard_args 150 { 151 void const * p_src; 152 void * p_dest; 153 uint32_t const length; 154 spi_bit_width_t const bit_width; 155 } spi_write_read_guard_args_t; 156 157 /** SPI interface configuration */ 158 typedef struct st_spi_cfg 159 { 160 uint8_t channel; ///< Channel number to be used 161 162 IRQn_Type rxi_irq; ///< Receive Buffer Full IRQ number 163 IRQn_Type txi_irq; ///< Transmit Buffer Empty IRQ number 164 IRQn_Type tei_irq; ///< Transfer Complete IRQ number 165 IRQn_Type eri_irq; ///< Error IRQ number 166 uint8_t rxi_ipl; ///< Receive Interrupt priority 167 uint8_t txi_ipl; ///< Transmit Interrupt priority 168 uint8_t tei_ipl; ///< Transfer Complete Interrupt priority 169 uint8_t eri_ipl; ///< Error Interrupt priority 170 spi_mode_t operating_mode; ///< Select master or slave operating mode 171 spi_clk_phase_t clk_phase; ///< Data sampling on odd or even clock edge 172 spi_clk_polarity_t clk_polarity; ///< Clock level when idle 173 spi_mode_fault_t mode_fault; ///< Mode fault error (master/slave conflict) flag 174 spi_bit_order_t bit_order; ///< Select to transmit MSB/LSB first 175 transfer_instance_t const * p_transfer_tx; ///< To use SPI DTC/DMAC write transfer, link a transfer instance here. Set to NULL if unused. 176 transfer_instance_t const * p_transfer_rx; ///< To use SPI DTC/DMAC read transfer, link a transfer instance here. Set to NULL if unused. 177 void (* p_callback)(spi_callback_args_t * p_args); ///< Pointer to user callback function 178 void const * p_context; ///< User defined context passed to callback function 179 void const * p_extend; ///< Extended SPI hardware dependent configuration 180 } spi_cfg_t; 181 182 /** SPI control block. Allocate an instance specific control block to pass into the SPI API calls. 183 */ 184 typedef void spi_ctrl_t; 185 186 /** Shared Interface definition for SPI */ 187 typedef struct st_spi_api 188 { 189 /** Initialize a channel for SPI communication mode. 190 * 191 * @param[in, out] p_ctrl Pointer to user-provided storage for the control block. 192 * @param[in] p_cfg Pointer to SPI configuration structure. 193 */ 194 fsp_err_t (* open)(spi_ctrl_t * p_ctrl, spi_cfg_t const * const p_cfg); 195 196 /** Receive data from a SPI device. 197 * 198 * @param[in] p_ctrl Pointer to the control block for the channel. 199 * @param[out] p_dest Pointer to destination buffer into which data will be copied that is received from a SPI 200 * device. It is the responsibility of the caller to ensure that adequate space is available 201 * to hold the requested data count. 202 * @param[in] length Number of units of data to be transferred (unit size specified by the 203 * bit_width). 204 * @param[in] bit_width Data bit width to be transferred. 205 */ 206 fsp_err_t (* read)(spi_ctrl_t * const p_ctrl, void * p_dest, uint32_t const length, 207 spi_bit_width_t const bit_width); 208 209 /** Transmit data to a SPI device. 210 * 211 * @param[in] p_ctrl Pointer to the control block for the channel. 212 * @param[in] p_src Pointer to a source data buffer from which data will be transmitted to a SPI device. 213 * The argument must not be NULL. 214 * @param[in] length Number of units of data to be transferred (unit size specified by the 215 * bit_width). 216 * @param[in] bit_width Data bit width to be transferred. 217 */ 218 fsp_err_t (* write)(spi_ctrl_t * const p_ctrl, void const * p_src, uint32_t const length, 219 spi_bit_width_t const bit_width); 220 221 /** Simultaneously transmit data to a SPI device while receiving data from a SPI device (full duplex). 222 * 223 * @param[in] p_ctrl Pointer to the control block for the channel. 224 * @param[in] p_src Pointer to a source data buffer from which data will be transmitted to a SPI device. 225 * The argument must not be NULL. 226 * @param[out] p_dest Pointer to destination buffer into which data will be copied that is received from a SPI 227 * device. It is the responsibility of the caller to ensure that adequate space is available 228 * to hold the requested data count. The argument must not be NULL. 229 * @param[in] length Number of units of data to be transferred (unit size specified by the bit_width). 230 * @param[in] bit_width Data bit width to be transferred. 231 */ 232 fsp_err_t (* writeRead)(spi_ctrl_t * const p_ctrl, void const * p_src, void * p_dest, uint32_t const length, 233 spi_bit_width_t const bit_width); 234 235 /** 236 * Specify callback function and optional context pointer and working memory pointer. 237 * 238 * @param[in] p_ctrl Pointer to the SPI control block. 239 * @param[in] p_callback Callback function 240 * @param[in] p_context Pointer to send to callback function 241 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 242 * Callback arguments allocated here are only valid during the callback. 243 */ 244 fsp_err_t (* callbackSet)(spi_ctrl_t * const p_ctrl, void (* p_callback)(spi_callback_args_t *), 245 void const * const p_context, spi_callback_args_t * const p_callback_memory); 246 247 /** Remove power to the SPI channel designated by the handle and disable the associated interrupts. 248 * 249 * @param[in] p_ctrl Pointer to the control block for the channel. 250 */ 251 fsp_err_t (* close)(spi_ctrl_t * const p_ctrl); 252 } spi_api_t; 253 254 /** This structure encompasses everything that is needed to use an instance of this interface. */ 255 typedef struct st_spi_instance 256 { 257 spi_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 258 spi_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 259 spi_api_t const * p_api; ///< Pointer to the API structure for this instance 260 } spi_instance_t; 261 262 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 263 FSP_FOOTER 264 265 /*****************************************************************************************************************//** 266 * @} (end defgroup SPI_API) 267 ********************************************************************************************************************/ 268 269 #endif 270
