1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 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 * Description: Provides HAL SPI \n 16 * 17 * History: \n 18 * 2022-08-08, Create file. \n 19 */ 20 #ifndef HAL_SPI_H 21 #define HAL_SPI_H 22 23 #include <stdint.h> 24 #include <stdbool.h> 25 #include "errcode.h" 26 #include "common_def.h" 27 #include "spi_porting.h" 28 29 #ifdef __cplusplus 30 #if __cplusplus 31 extern "C" { 32 #endif /* __cplusplus */ 33 #endif /* __cplusplus */ 34 35 /** 36 * @defgroup drivers_hal_spi_api SPI 37 * @ingroup drivers_hal_spi 38 * @{ 39 */ 40 41 /** 42 * @if Eng 43 * @brief Definition of the contorl ID of hal SPI. 44 * @else 45 * @brief SPI控制ID定义。 46 * @endif 47 */ 48 typedef enum hal_spi_ctrl_id { 49 SPI_CTRL_SET_ATTR, /*!< @if Eng Set SPI basic attribute. 50 @else 设置基础参数。 @endif */ 51 52 SPI_CTRL_GET_ATTR, /*!< @if Eng Get SPI basic attribute. 53 @else 获取基础参数。 @endif */ 54 55 SPI_CTRL_SET_EXTRA_ATTR, /*!< @if Eng Set SPI extral attribute. 56 @else 设置高级参数。 @endif */ 57 58 SPI_CTRL_GET_EXTRA_ATTR, /*!< @if Eng Get SPI extral attribute. 59 @else 获取高级参数。 @endif */ 60 61 SPI_CTRL_SELECT_SLAVE, /*!< @if Eng Select the slave. 62 @else 选择指定的设备。 @endif */ 63 64 SPI_CTRL_CHECK_FIFO_BUSY, /*!< @if Eng Check whether the SPI is busy. 65 @else 检查SPI是否忙碌状态。 @endif */ 66 #if defined(CONFIG_SPI_SUPPORT_DMA) && (CONFIG_SPI_SUPPORT_DMA == 1) 67 SPI_CTRL_SET_DMA_CFG, /*!< @if Eng Set the DMA transfer enable/disable and datalevel. 68 @else 设置DMA的传输使能和数据level。 @endif */ 69 70 SPI_CTRL_GET_DMA_DATA_ADDR, /*!< @if Eng Get the DMA transfer data address. 71 @else 获取DMA的传输数据地址。 @endif */ 72 #endif /* CONFIG_SPI_SUPPORT_DMA */ 73 74 #if defined(CONFIG_SPI_SUPPORT_INTERRUPT) && (CONFIG_SPI_SUPPORT_INTERRUPT == 1) 75 SPI_CTRL_EN_RXFI_INT, /*!< @if Eng Enable the Receive FIFO full interrupt. 76 @else 使能RX FIFO是否已满中断。 @endif */ 77 78 SPI_CTRL_CHECK_RX_FIFO_EMPTY, /*!< @if Eng Check if rx fifo is empty or not. 79 @else 判断RX FIFO是否为空。 @endif */ 80 81 SPI_CTRL_EN_TXEI_INT, /*!< @if Eng Enable the transmit FIFO empty interrupt. 82 @else 使能TX FIFO是否为空中断。 @endif */ 83 84 SPI_CTRL_CHECK_TX_FIFO_FULL, /*!< @if Eng Check if tx fifo is full or not. 85 @else 判断RX FIFO是否已满。 @endif */ 86 87 SPI_CTRL_EN_MULTI_MASTER_ERR_INT, /*!< @if Eng Enable the Multi-Master contention interrupt. 88 @else 使能双主机竞争中断。 @endif */ 89 #endif /* CONFIG_SPI_SUPPORT_INTERRUPT */ 90 91 #if defined(CONFIG_SPI_SUPPORT_LPM) && (CONFIG_SPI_SUPPORT_LPM == 1) 92 SPI_CTRL_SUSPEND, /*!< @if Eng Suspend all of the spi channels. 93 @else 挂起所有spi通道。 @endif */ 94 SPI_CTRL_RESUME, /*!< @if Eng Resume all of the spi channels. 95 @else 挂起所有spi通道。 @endif */ 96 #endif /* CONFIG_SPI_SUPPORT_LPM */ 97 SPI_CTRL_SET_TMOD, /*!< @if Eng Set SPI transfer mode. 98 @else 设置SPI传输模式。 @endif */ 99 SPI_CTRL_MAX, 100 SPI_CTRL_ID_INVALID = 0xFF 101 } hal_spi_ctrl_id_t; 102 103 /** 104 * @if Eng 105 * @brief Frame Format. 106 * @else 107 * @brief 帧格式。 108 * @endif 109 */ 110 typedef enum hal_spi_cfg_frame_format { 111 SPI_CFG_FRAME_FORMAT_MOTOROLA_SPI, /*!< @if Eng Motorolla SPI Frame Format. 112 @else 摩托罗拉SPI帧格式。 @endif */ 113 114 SPI_CFG_FRAME_FORMAT_TEXAS_SSP, /*!< @if Eng Texas Instruments SSP Frame Format. 115 @else 德州仪器SSP帧格式。 @endif */ 116 117 SPI_CFG_FRAME_FORMAT_NS_MICROWIRE, /*!< @if Eng National Microwire Frame Format. 118 @else 国家微线帧格式。 @endif */ 119 SPI_CFG_FRAME_FORMAT_MAX 120 } hal_spi_cfg_frame_format_t; 121 122 /** 123 * @if Eng 124 * @brief Clock polarity. 125 * @else 126 * @brief 时钟极性。 127 * @endif 128 */ 129 typedef enum hal_spi_cfg_clk_cpol { 130 SPI_CFG_CLK_CPOL_0, /*!< @if Eng Inactive state of serial clock is low. 131 @else SPI的非激活状态为低电平。 @endif */ 132 133 SPI_CFG_CLK_CPOL_1, /*!< @if Eng Inactive state of serial clock is high. 134 @else SPI的非激活状态为高电平。 @endif */ 135 SPI_CFG_CLK_CPOL_MAX 136 } hal_spi_cfg_clk_cpol_t; 137 138 /** 139 * @if Eng 140 * @brief Clock phase. 141 * @else 142 * @brief 时钟相位。 143 * @endif 144 */ 145 typedef enum hal_spi_cfg_clk_cpha { 146 SPI_CFG_CLK_CPHA_0, /*!< @if Eng Serial clock toggles in middle of first data bit. 147 @else SPI时钟在第一个数据位中间切换。 @endif */ 148 149 SPI_CFG_CLK_CPHA_1, /*!< @if Eng Serial clock toggles at start of first data bit. 150 @else SPI时钟在第一个数据位开始时切换。 @endif */ 151 SPI_CFG_CLK_CPHA_MAX 152 } hal_spi_cfg_clk_cpha_t; 153 154 /** 155 * @if Eng 156 * @brief SPI slave select toggle enable. 157 * @else 158 * @brief SPI 从机选择切换使能 159 * @endif 160 */ 161 typedef enum hal_spi_cfg_sste { 162 SPI_CFG_SSTE_DISABLE, /*!< @if Eng SPI slave select toggle disable. 163 When disable, master should reed all data in slave tx_queue 164 at ONE time when reading data from slave device. Otherwise, 165 data loss occurs. 166 @else SPI 从机选择切换不使能。 167 当此配置不使能，主机从从机读取数据时，需要一次性将从机发送 168 队列中的数据读完，否则会出现丢失数据问题。@endif */ 169 SPI_CFG_SSTE_ENABLE, /*!< @if Eng SPI slave select toggle enable. 170 @else SPI 从机选择切换使能 @endif */ 171 SPI_CFG_SSTE_MAX 172 } hal_spi_cfg_sste_t; 173 174 /** 175 * @if Eng 176 * @brief Transfer Mode. 177 * @else 178 * @brief 传输模式。 179 * @endif 180 */ 181 typedef enum hal_spi_trans_mode { 182 HAL_SPI_TRANS_MODE_TXRX = 0, /*!< @if Eng Transmit and receive mode. 183 @else 收发模式。 @endif */ 184 185 HAL_SPI_TRANS_MODE_TX, /*!< @if Eng Transmit only / Transmit mode. 186 @else 发送模式。 @endif */ 187 188 HAL_SPI_TRANS_MODE_RX, /*!< @if Eng Receive only / Receive mode. 189 @else 接收模式。 @endif */ 190 191 HAL_SPI_TRANS_MODE_EEPROM, /*!< @if Eng EEPROM read mode. 192 @else EEPROM模式。 @endif */ 193 HAL_SPI_TRANS_MODE_MAX 194 } hal_spi_trans_mode_t; 195 196 /** 197 * @if Eng 198 * @brief Data Frame Size. 199 * @else 200 * @brief 数据帧长度。 201 * @endif 202 */ 203 typedef enum hal_spi_frame_size { 204 HAL_SPI_FRAME_SIZE_8 = 0x07, /*!< @if Eng 8-bit serial data transfer. 205 @else 8-位串行数据传输。 @endif */ 206 207 HAL_SPI_FRAME_SIZE_16 = 0x0F, /*!< @if Eng 16-bit serial data transfer(Not supported now). 208 @else 16-位串行数据传输（暂不支持）。 @endif */ 209 210 HAL_SPI_FRAME_SIZE_24 = 0x17, /*!< @if Eng 24-bit serial data transfer(Not supported now). 211 @else 24-位串行数据传输（暂不支持）。 @endif */ 212 213 HAL_SPI_FRAME_SIZE_32 = 0x1F /*!< @if Eng 32-bit serial data transfer. 214 @else 32-位串行数据传输。 @endif */ 215 } hal_spi_frame_size_t; 216 217 /** 218 * @if Eng 219 * @brief SPI Frame Format. 220 * @else 221 * @brief SPI数据帧格式。 222 * @endif 223 */ 224 typedef enum hal_spi_frame_format { 225 HAL_SPI_FRAME_FORMAT_STANDARD = 0, /*!< @if Eng SPI Standard frame format. 226 @else 标准的单线SPI帧格式。 @endif */ 227 228 HAL_SPI_FRAME_FORMAT_DUAL, /*!< @if Eng SPI Dual frame format. 229 @else 双线SPI帧格式。 @endif */ 230 231 HAL_SPI_FRAME_FORMAT_QUAD, /*!< @if Eng SPI Quad frame format. 232 @else 4线SPI帧格式。 @endif */ 233 234 HAL_SPI_FRAME_FORMAT_OCTAL, /*!< @if Eng SPI Octal frame format. 235 @else 8线SPI帧格式。 @endif */ 236 237 HAL_SPI_FRAME_FORMAT_DOUBLE_OCTAL, /*!< @if Eng SPI Double Octal frame format. 238 @else 16线SPI帧格式。 @endif */ 239 HAL_SPI_FRAME_FORMAT_SIXT, 240 HAL_SPI_FRAME_FORMAT_MAX_NUM, 241 HAL_SPI_FRAME_FORMAT_NONE = HAL_SPI_FRAME_FORMAT_MAX_NUM 242 } hal_spi_frame_format_t; 243 244 /** 245 * @if Eng 246 * @brief SPI Transfer Types. 247 * @else 248 * @brief SPI传输类型。 249 * @endif 250 */ 251 typedef enum hal_spi_trans_type { 252 HAL_SPI_TRANS_TYPE_INST_S_ADDR_S = 0, /*!< @if Eng Instruction and Address will be sent in standard SPI mode. 253 @else 指令和地址使用单线SPI传输。 @endif */ 254 255 HAL_SPI_TRANS_TYPE_INST_S_ADDR_Q, /*!< @if Eng Instruction will be sent in standard mode and address will 256 be sent in mode specified by frame format register. 257 @else 指令使用单线SPI传输， 258 地址按照帧格式寄存器的配置传输。 @endif */ 259 260 HAL_SPI_TRANS_TYPE_INST_Q_ADDR_Q, /*!< @if Eng Both instruction and address will be sent in 261 the mode specified by frame format register. 262 @else 指令和地址都按照帧格式寄存器的配置传输。 @endif */ 263 HAL_SPI_TRANS_TYPE_MAX = HAL_SPI_TRANS_TYPE_INST_Q_ADDR_Q 264 } hal_spi_trans_type_t; 265 266 /** 267 * @if Eng 268 * @brief SPI length of instruction. 269 * @else 270 * @brief SPI指令长度定义。 271 * @endif 272 */ 273 typedef enum hal_spi_inst_len { 274 HAL_SPI_INST_LEN_0 = 0, /*!< @if Eng 0-bit (no instruction). 275 @else 不携带指令。 @endif */ 276 277 HAL_SPI_INST_LEN_4, /*!< @if Eng 4-bit instruction. 278 @else 4-位指令。 @endif */ 279 280 HAL_SPI_INST_LEN_8, /*!< @if Eng 8-bit instruction. 281 @else 8-位指令。 @endif */ 282 283 HAL_SPI_INST_LEN_16, /*!< @if Eng 16-bit instruction. 284 @else 16-位指令。 @endif */ 285 HAL_SPI_INST_LEN_MAX = HAL_SPI_INST_LEN_16 286 } hal_spi_inst_len_t; 287 288 /** 289 * @if Eng 290 * @brief SPI length of address. 291 * @else 292 * @brief SPI地址长度定义。 293 * @endif 294 */ 295 typedef enum hal_spi_addr_len { 296 HAL_SPI_ADDR_LEN_0 = 0, /*!< @if Eng 0-bit address length. 297 @else 0-位地址长度。 @endif */ 298 299 HAL_SPI_ADDR_LEN_4, /*!< @if Eng 4-bit address length. 300 @else 4-位地址长度。 @endif */ 301 302 HAL_SPI_ADDR_LEN_8, /*!< @if Eng 8-bit address length. 303 @else 8-位地址长度。 @endif */ 304 305 HAL_SPI_ADDR_LEN_12, /*!< @if Eng 12-bit address length. 306 @else 12-位地址长度。 @endif */ 307 308 HAL_SPI_ADDR_LEN_16, /*!< @if Eng 16-bit address length. 309 @else 16-位地址长度。 @endif */ 310 311 HAL_SPI_ADDR_LEN_20, /*!< @if Eng 20-bit address length. 312 @else 20-位地址长度。 @endif */ 313 314 HAL_SPI_ADDR_LEN_24, /*!< @if Eng 24-bit address length. 315 @else 24-位地址长度。 @endif */ 316 317 HAL_SPI_ADDR_LEN_28, /*!< @if Eng 28-bit address length. 318 @else 28-位地址长度。 @endif */ 319 320 HAL_SPI_ADDR_LEN_32, /*!< @if Eng 32-bit address length. 321 @else 32-位地址长度。 @endif */ 322 323 HAL_SPI_ADDR_LEN_36, /*!< @if Eng 36-bit address length. 324 @else 36-位地址长度。 @endif */ 325 326 HAL_SPI_ADDR_LEN_40, /*!< @if Eng 40-bit address length. 327 @else 40-位地址长度。 @endif */ 328 329 HAL_SPI_ADDR_LEN_44, /*!< @if Eng 44-bit address length. 330 @else 44-位地址长度。 @endif */ 331 332 HAL_SPI_ADDR_LEN_48, /*!< @if Eng 48-bit address length. 333 @else 48-位地址长度。 @endif */ 334 335 HAL_SPI_ADDR_LEN_52, /*!< @if Eng 52-bit address length. 336 @else 52-位地址长度。 @endif */ 337 338 HAL_SPI_ADDR_LEN_56, /*!< @if Eng 56-bit address length. 339 @else 56-位地址长度。 @endif */ 340 341 HAL_SPI_ADDR_LEN_60, /*!< @if Eng 60-bit address length. 342 @else 60-位地址长度。 @endif */ 343 HAL_SPI_ADDR_LEN_MAX = HAL_SPI_ADDR_LEN_60 344 } hal_spi_addr_len_t; 345 346 /** 347 * @if Eng 348 * @brief Definition of the event ID of hal spi. 349 * @else 350 * @brief HAL层SPI事件ID的定义 351 * @endif 352 */ 353 typedef enum hal_spi_evt_id { 354 SPI_EVT_RX_FULL_ISR, /*!< @if Eng Rx full isr triggered. 355 @else 接收满中断触发 @endif */ 356 SPI_EVT_RX_OVERFLOW_ISR, /*!< @if Eng Rx overflow isr triggered. 357 @else 接收溢出中断触发 @endif */ 358 SPI_EVT_RX_UNDERFLOW_ISR, /*!< @if Eng Rx underflow isr triggered. 359 @else 接收空读中断触发 @endif */ 360 SPI_EVT_TX_EMPTY_ISR, /*!< @if Eng Tx empty isr triggered. 361 @else TX空中断被触发 @endif */ 362 SPI_EVT_TX_OVERFLOW_ISR, /*!< @if Eng Tx overflow isr triggered. 363 @else TX溢出中断被触发 @endif */ 364 SPI_EVT_MULTI_MASTER_ISR /*!< @if Eng Multi-master contention isr triggered. 365 @else 双主机竞争中断被触发 @endif */ 366 } hal_spi_evt_id_t; 367 368 /** 369 * @if Eng 370 * @brief QSPI parameters of SPI transfer. 371 * @else 372 * @brief SPI传输中QSPI的参数。 373 * @endif 374 */ 375 typedef struct hal_spi_xfer_qspi_param { 376 hal_spi_trans_type_t trans_type; /*!< @if Eng SPI frame format for instruction and address. 377 @else 传输类型，用于指定指令和地址的长度。 @endif */ 378 379 hal_spi_inst_len_t inst_len; /*!< @if Eng Instruction length, support 0, 4, 8, 16bits. 380 @else 指令长度，支持0、4、8、16位。 @endif */ 381 382 hal_spi_addr_len_t addr_len; /*!< @if Eng Address length, support 0, 8, 16, 24, 32bits. 383 @else 地址长度，支持0、8、16、24、32位。 @endif */ 384 385 uint32_t wait_cycles; /*!< @if Eng Indicates the wait cycles. 386 @else 等待的周期数。 @endif */ 387 } hal_spi_xfer_qspi_param_t; 388 389 /** 390 * @if Eng 391 * @brief Single SPI parameters of SPI transfer. 392 * @else 393 * @brief SPI传输中Single SPI的参数。 394 * @endif 395 */ 396 typedef struct hal_spi_xfer_sspi_param { 397 uint32_t wait_cycles; /*!< @if Eng Indicates the wait cycles. 398 @else 等待的周期数。 @endif */ 399 } hal_spi_xfer_sspi_param_t; 400 401 /** 402 * @if Eng 403 * @brief Definition of SPI basic attributes. 404 * @else 405 * @brief SPI基础配置参数定义。 406 * @endif 407 */ 408 typedef struct hal_spi_attr { 409 bool is_slave; /*!< @if Eng Indicates if SPI work in slave mode or not. 410 @else SPI工作在Master/Slave模式。 @endif */ 411 412 uint32_t slave_num; /*!< @if Eng Index when selecting a slave. 413 - 0: Not select. 414 - 1: slave index 0. 415 - 2: slave index 1. 416 - ... 417 @else 选择从机时的索引 418 - 0：不选择。 419 - 1：从机索引0。 420 - 2：从机索引1。 421 - ... 422 @endif */ 423 424 uint32_t bus_clk; /*!< @if Eng Provide ssi_clk for clock freq division calculation. 425 @else 用于计算SPI的时钟分频系数。 @endif */ 426 427 uint32_t freq_mhz; /*!< @if Eng Indicates the frequency of SPI. 428 @else SPI的工作频率。 @endif */ 429 430 uint32_t clk_polarity; /*!< @if Eng Indicates the clock polarity of SPI. 431 For details, see @ref hal_spi_cfg_clk_cpol_t 432 @else SPI的时钟极性。参考 @ref hal_spi_cfg_clk_cpol_t @endif */ 433 434 uint32_t clk_phase; /*!< @if Eng Indicates the clock phase of SPI. 435 For details, see @ref hal_spi_cfg_clk_cpha_t 436 @else SPI的时钟相位。参考 @ref hal_spi_cfg_clk_cpha_t @endif */ 437 438 uint32_t frame_format; /*!< @if Eng Indicates the which serial protocol transfers the data. 439 For details, see @ref hal_spi_cfg_frame_format_t 440 @else 选择串行传输的协议。参考 @ref hal_spi_cfg_frame_format_t @endif */ 441 442 uint32_t spi_frame_format; /*!< @if Eng Indicates the frame format of SPI. 443 For details, see @ref hal_spi_frame_format_t 444 @else SPI的帧格式。参考 @ref hal_spi_frame_format_t @endif */ 445 446 uint32_t frame_size; /*!< @if Eng Indicates the frame size of SPI. 447 For details, see @ref hal_spi_frame_size_t 448 @else SPI的帧长度。参考 @ref hal_spi_frame_size_t @endif */ 449 450 uint32_t tmod; /*!< @if Eng Indicates the transfer mode. 451 For details, see @ref hal_spi_trans_mode_t 452 @else SPI的传输模式。参考 @ref hal_spi_trans_mode_t @endif */ 453 454 uint32_t ndf; /*!< @if Eng Indicates the number of data frames. 455 @else SPI的数据帧数。 @endif */ 456 457 uint32_t sste; /*!< @if Eng Indicates if SPI slave select toggle enable or not. 458 When disable, master should reed all data in slave tx_queue 459 at ONE time when reading data from slave device. Otherwise, 460 data loss occurs. 461 For details, see @ref hal_spi_cfg_sste_t 462 @else SPI从机选择切换使能/不使能。 463 当此配置不使能，主机从从机读取数据时，需要一次性将从机发送 464 队列中的数据读完，否则会出现丢失数据问题。 465 参考 @ref hal_spi_cfg_sste_t @endif */ 466 } hal_spi_attr_t; 467 468 /** 469 * @if Eng 470 * @brief Definition of SPI extra attributes. 471 * @else 472 * @brief SPI扩展配置参数定义。 473 * @endif 474 */ 475 typedef struct hal_spi_extra_attr { 476 bool tx_use_dma; /*!< @if Eng Indicates if SPI use dma or not in TX. 477 @else SPI是否使用DMA发送数据。 @endif */ 478 479 bool rx_use_dma; /*!< @if Eng Indicates if SPI use dma or not in RX. 480 @else SPI是否使用DMA接收数据。 @endif */ 481 482 hal_spi_xfer_qspi_param_t qspi_param; /*!< @if Eng Indicates the qspi parameters. 483 @else QSPI参数。 @endif */ 484 485 hal_spi_xfer_sspi_param_t sspi_param; /*!< @if Eng Indicates the single spi parameters. 486 @else Single SPI参数。 @endif */ 487 } hal_spi_extra_attr_t; 488 489 /** 490 * @if Eng 491 * @brief SPI transfer data structure. 492 * @else 493 * @brief SPI传输结构体。 494 * @endif 495 */ 496 typedef struct hal_spi_xfer_data { 497 uint8_t *tx_buff; /*!< @if Eng Buff to send data through tx fifo. 498 @else 通过tx fifo发送数据的Buff。 @endif */ 499 uint32_t tx_bytes; /*!< @if Eng Bytes of data need to send. For details, see @ref hal_spi_attr_t.frame_size. 500 when frame_size is HAL_SPI_FRAME_SIZE_8, The value must be a multiple of 1. 501 when frame_size is HAL_SPI_FRAME_SIZE_16, The value must be a multiple of 2. 502 when frame_size is HAL_SPI_FRAME_SIZE_24, The value must be a multiple of 3. 503 when frame_size is HAL_SPI_FRAME_SIZE_32, The value must be a multiple of 4. 504 @else 发送数据的个数。参考 @ref hal_spi_attr_t.frame_size. 505 如果frame_size为HAL_SPI_FRAME_SIZE_8，则需设定为1的倍数 506 如果frame_size为HAL_SPI_FRAME_SIZE_16，则需设定为2的倍数 507 如果frame_size为HAL_SPI_FRAME_SIZE_24，则需设定为3的倍数 508 如果frame_size为HAL_SPI_FRAME_SIZE_32，则需设定为4的倍数 509 @endif */ 510 uint8_t *rx_buff; /*!< @if Eng Buff to receive data from rx fifo. 511 @else 通过rx fifo接收数据的Buff。 @endif */ 512 uint32_t rx_bytes; /*!< @if Eng Bytes of data need to receive, For details, see @ref hal_spi_attr_t.frame_size. 513 when frame_size is HAL_SPI_FRAME_SIZE_8, The value must be a multiple of 1. 514 when frame_size is HAL_SPI_FRAME_SIZE_16, The value must be a multiple of 2. 515 when frame_size is HAL_SPI_FRAME_SIZE_24, The value must be a multiple of 3. 516 when frame_size is HAL_SPI_FRAME_SIZE_32, The value must be a multiple of 4. 517 @else 接收数据的个数。参考 @ref hal_spi_attr_t.frame_size. 518 如果frame_size为HAL_SPI_FRAME_SIZE_8，则需设定为1的倍数 519 如果frame_size为HAL_SPI_FRAME_SIZE_16，则需设定为2的倍数 520 如果frame_size为HAL_SPI_FRAME_SIZE_24，则需设定为3的倍数 521 如果frame_size为HAL_SPI_FRAME_SIZE_32，则需设定为4的倍数 522 @endif */ 523 uint8_t cmd; /*!< @if Eng Command for QSPI mode. 524 @else QSPI模式下的命令。 @endif */ 525 uint8_t reserved[3]; /*!< @if Eng Reserved. 526 @else 保留。 @endif */ 527 uint32_t addr; /*!< @if Eng Address for QSPI mode. 528 @else QSPI模式下的地址。 @endif */ 529 } hal_spi_xfer_data_t; 530 531 #if defined(CONFIG_SPI_SUPPORT_DMA) && (CONFIG_SPI_SUPPORT_DMA == 1) 532 /** 533 * @if Eng 534 * @brief DMA SPI parameters of SPI transfer. 535 * @else 536 * @brief SPI传输中DMA SPI的参数。 537 * @endif 538 */ 539 typedef struct hal_spi_dma_cfg_param { 540 bool is_enable; /*!< @if Eng DMA transfer enable/disable configuration. 541 @else DMA传输使能配置。 @endif */ 542 uint8_t dma_rx_level; /*!< @if Eng DMA receive data level configuration. 543 @else DMA RX传输请求的数据level配置。 @endif */ 544 uint8_t dma_tx_level; /*!< @if Eng DMA transmit data level configuration. 545 @else DMA TX传输请求的数据level配置。 @endif */ 546 } hal_spi_dma_cfg_param_t; 547 #endif /* CONFIG_SPI_SUPPORT_DMA */ 548 549 /** 550 * @if Eng 551 * @brief Callback of SPI. 552 * @param [in] bus The SPI bus. see @ref spi_bus_t 553 * @param [in] evt Event ID. 554 * @param [in] param Parameter of callback. 555 * @retval ERRCODE_SUCC Success. 556 * @retval Other Failure. For details, see @ref errcode_t 557 * @else 558 * @brief SPI的回调函数 559 * @param [in] bus 串口号， 参考 @ref spi_bus_t 560 * @param [in] evt 事件ID. 561 * @param [in] param 传递到回调的参数 562 * @retval ERRCODE_SUCC 成功 563 * @retval Other 失败，参考 @ref errcode_t 564 * @endif 565 */ 566 typedef errcode_t (*hal_spi_callback_t)(spi_bus_t bus, hal_spi_evt_id_t evt, uintptr_t param); 567 568 /** 569 * @if Eng 570 * @brief Control interface for hal SPI. 571 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t 572 * @param [in] id ID of the SPI control. 573 * @param [in] param Parameter for callback. 574 * @retval ERRCODE_SUCC Success. 575 * @retval Other Failure. For details, see @ref errcode_t 576 * @else 577 * @brief HAL层SPI控制接口。 578 * @param [in] bus 串口号。参考 @ref spi_bus_t 579 * @param [in] id SPI控制请求ID。 580 * @param [in] param 传递给控制回调的参数。 581 * @retval ERRCODE_SUCC 成功。 582 * @retval Other 失败。参考 @ref errcode_t 583 * @endif 584 */ 585 typedef errcode_t (*hal_spi_ctrl_t)(spi_bus_t bus, hal_spi_ctrl_id_t id, uintptr_t param); 586 587 /** 588 * @if Eng 589 * @brief Init device for hal SPI. 590 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t 591 * @param [in] attr SPI basic attributes. 592 * @param [in] extra_attr SPI extra attributes. 593 * @param [in] callback SPI callback function. 594 * @retval ERRCODE_SUCC Success. 595 * @retval Other Failure. For details, see @ref errcode_t 596 * @else 597 * @brief HAL层SPI的初始化接口。 598 * @param [in] bus SPI端口号。参考 @ref spi_bus_t 599 * @param [in] attr SPI的基本配置参数。 600 * @param [in] extra_attr SPI高级配置参数。 601 * @param [in] callback SPI回调函数。 602 * @retval ERRCODE_SUCC 成功。 603 * @retval Other 失败。参考 @ref errcode_t 604 * @endif 605 */ 606 errcode_t hal_spi_init(spi_bus_t bus, const hal_spi_attr_t *attr, 607 const hal_spi_extra_attr_t *extra_attr, hal_spi_callback_t callback); 608 609 /** 610 * @if Eng 611 * @brief Deinit device for hal SPI. 612 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t 613 * @retval ERRCODE_SUCC Success. 614 * @retval Other Failure. For details, see @ref errcode_t 615 * @else 616 * @brief HAL层SPI的去初始化接口。 617 * @param [in] bus SPI端口号。参考 @ref spi_bus_t 618 * @retval ERRCODE_SUCC 成功。 619 * @retval Other 失败。参考 @ref errcode_t 620 * @endif 621 */ 622 errcode_t hal_spi_deinit(spi_bus_t bus); 623 624 /** 625 * @if Eng 626 * @brief Write interface for hal SPI. 627 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t 628 * @param [in] data Transfer data. For details, see @ref hal_spi_xfer_data_t 629 * @param [in] timeout Timeout duration. 630 * @retval ERRCODE_SUCC Success. 631 * @retval Other Failure. For details, see @ref errcode_t 632 * @else 633 * @brief HAL层SPI发送数据接口。 634 * @param [in] bus 串口号。参考 @ref spi_bus_t 635 * @param [in] data 传输数据。参考 @ref hal_spi_xfer_data_t 636 * @param [in] timeout 超时时间。 637 * @retval ERRCODE_SUCC 成功。 638 * @retval Other 失败。参考 @ref errcode_t 639 * @endif 640 */ 641 errcode_t hal_spi_write(spi_bus_t bus, hal_spi_xfer_data_t *data, uint32_t timeout); 642 643 /** 644 * @if Eng 645 * @brief Read interface for hal SPI(When timeout is zero, will be exited If the data is full or no data is fifo). 646 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t 647 * @param [out] data Transfer data. For details, see @ref hal_spi_xfer_data_t 648 * @param [in] timeout Timeout duration. 649 * @retval ERRCODE_SUCC Success. 650 * @retval Other Failure. For details, see @ref errcode_t 651 * @else 652 * @brief HAL层SPI读取数据接口(当timeout为0时会在数据读满或者fifo中没有数据的时候结束)。 653 * @param [in] bus 串口号。参考 @ref spi_bus_t 654 * @param [out] data 传输数据。参考 @ref hal_spi_xfer_data_t 655 * @param [in] timeout 超时时间。 656 * @retval ERRCODE_SUCC 成功。 657 * @retval Other 失败。参考 @ref errcode_t 658 * @endif 659 */ 660 errcode_t hal_spi_read(spi_bus_t bus, hal_spi_xfer_data_t *data, uint32_t timeout); 661 662 /** 663 * @if Eng 664 * @brief Control interface for hal SPI. 665 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t 666 * @param [in] id ID of the SPI control. 667 * @param [in] param Parameter for callback. 668 * @retval ERRCODE_SUCC Success. 669 * @retval Other Failure. For details, see @ref errcode_t 670 * @else 671 * @brief HAL层SPI控制接口。 672 * @param [in] bus 串口号。参考 @ref spi_bus_t 673 * @param [in] id SPI控制请求ID。 674 * @param [in] param 传递给控制回调的参数。 675 * @retval ERRCODE_SUCC 成功。 676 * @retval Other 失败。参考 @ref errcode_t 677 * @endif 678 */ 679 errcode_t hal_spi_ctrl(spi_bus_t bus, hal_spi_ctrl_id_t id, uintptr_t param); 680 681 /** 682 * @if Eng 683 * @brief Init the registers of SPI IPs. 684 * @retval ERRCODE_SUCC Success. 685 * @retval Other Failure. For details, see @ref errcode_t 686 * @else 687 * @brief 初始化寄存器基地址列表。 688 * @retval ERRCODE_SUCC 成功。 689 * @retval Other 失败。参考 @ref errcode_t 690 * @endif 691 */ 692 errcode_t hal_spi_regs_init(void); 693 694 /** 695 * @} 696 */ 697 698 #ifdef __cplusplus 699 #if __cplusplus 700 } 701 #endif /* __cplusplus */ 702 #endif /* __cplusplus */ 703 704 #endif 705