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: Provide SPI driver API \n 16 * 17 * History: \n 18 * 2022-09-15, Create file. \n 19 */ 20 #ifndef SPI_H 21 #define SPI_H 22 23 #include <stdint.h> 24 #include "errcode.h" 25 #include "hal_spi.h" 26 27 #ifdef __cplusplus 28 #if __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 #endif /* __cplusplus */ 32 33 /** 34 * @defgroup drivers_driver_spi SPI 35 * @ingroup drivers_driver 36 * @{ 37 */ 38 39 /** 40 * @if Eng 41 * @brief Definition of SPI attributes. 42 * @else 43 * @brief SPI基本属性定义。 44 * @endif 45 */ 46 typedef hal_spi_attr_t spi_attr_t; 47 48 /** 49 * @if Eng 50 * @brief Definition of SPI extral attributes. 51 * @else 52 * @brief SPI扩展属性定义。 53 * @endif 54 */ 55 typedef hal_spi_extra_attr_t spi_extra_attr_t; 56 57 /** 58 * @if Eng 59 * @brief SPI transfer data structure. 60 * @else 61 * @brief SPI传输结构体。 62 * @endif 63 */ 64 typedef hal_spi_xfer_data_t spi_xfer_data_t; 65 66 /** 67 * @if Eng 68 * @brief Definition of SPI DMA configuration. 69 * @else 70 * @brief SPI DMA配置数据结构定义。 71 * @endif 72 */ 73 typedef struct spi_dma_config { 74 uint8_t src_width; /*!< @if Eng Transfer data width of the source. 75 * - 0: 1byte 76 * - 1: 2byte 77 * - 2: 4byte 78 * @else 源端传输数据宽度。 \n 79 * - 0: 1字节 80 * - 1: 2字节 81 * - 2: 4字节 82 * @endif */ 83 uint8_t dest_width; /*!< @if Eng Transfer data width of the destination. 84 * - 0: 1byte 85 * - 1: 2byte 86 * - 2: 4byte 87 * @else 目的端传输数据宽度。 \n 88 * - 0: 1字节 89 * - 1: 2字节 90 * - 2: 4字节 91 * @endif */ 92 uint8_t burst_length; /*!< @if Eng Number of data items, to be written to the destination every time 93 * a destination burst transaction request is made from 94 * either the corresponding hardware or software handshaking interface. 95 * - 0: burst length is 1 96 * - 1: burst length is 4 97 * - 2: burst length is 8 98 * - 3: burst length is 16 99 * @else 每次从相应的硬件或软件握手接口发出目的burst请求时,要写入目的端数据量。 100 * - 0: burst长度是1 101 * - 1: burst长度是4 102 * - 2: burst长度是8 103 * - 3: burst长度是16 104 * @endif */ 105 uint8_t priority; /*!< @if Eng Transfer channel priority(Minimum: 0 and Maximum: 3). 106 * @else 传输通道优先级(最小为0以及最大为3)。 @endif */ 107 } spi_dma_config_t; 108 109 /** 110 * @if Eng 111 * @brief Initialize the SPI. 112 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 113 * @param [in] attr Basic configuration of SPI. For details, see @ref spi_attr_t. 114 * @param [in] extra_attr High-level configuration of SPI. For details, see @ref spi_extra_attr_t. 115 * @retval ERRCODE_SUCC Success. 116 * @retval Other Failure. For details, see @ref errcode_t. 117 * @else 118 * @brief 初始化 SPI。 119 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 120 * @param [in] attr SPI的基础配置参数，参考 @ref spi_attr_t 。 121 * @param [in] extra_attr SPI的高级配置参数，参考 @ref spi_extra_attr_t 。 122 * @retval ERRCODE_SUCC 成功。 123 * @retval Other 失败，参考 @ref errcode_t 。 124 * @endif 125 */ 126 errcode_t uapi_spi_init(spi_bus_t bus, spi_attr_t *attr, spi_extra_attr_t *extra_attr); 127 128 /** 129 * @if Eng 130 * @brief Deinitialize the SPI. 131 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 132 * @retval ERRCODE_SUCC Success. 133 * @retval Other Failure. For details, For details, see @ref errcode_t. 134 * @else 135 * @brief 去初始化 SPI。 136 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 137 * @retval ERRCODE_SUCC 成功。 138 * @retval Other 失败，参考 @ref errcode_t 。 139 * @endif 140 */ 141 errcode_t uapi_spi_deinit(spi_bus_t bus); 142 143 /** 144 * @if Eng 145 * @brief Set SPI Transmit mode. 146 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 147 * @param [in] tmod The SPI Transfer Mode. For details, see @ref hal_spi_trans_mode_t. 148 * @param [in] data_frame_num The Number of the SPI Rx Data frame. 149 * @retval ERRCODE_SUCC Success. 150 * @retval Other Failure. For details, For details, see @ref errcode_t. 151 * @else 152 * @brief 设置SPI的传输模式。 153 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 154 * @param [in] tmod SPI传输模式，参考 @ref hal_spi_trans_mode_t 。 155 * @param [in] data_frame_num SPI RX数据帧的数量。 156 * @retval ERRCODE_SUCC 成功。 157 * @retval Other 失败，参考 @ref errcode_t 。 158 * @endif 159 */ 160 errcode_t uapi_spi_set_tmod(spi_bus_t bus, hal_spi_trans_mode_t tmod, uint8_t data_frame_num); 161 162 /** 163 * @if Eng 164 * @brief Set SPI basic configuration. 165 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 166 * @param [in] attr Basic configuration of SPI. For details, see @ref spi_attr_t. 167 * @retval ERRCODE_SUCC Success. 168 * @retval Other Failure. For details, see @ref errcode_t. 169 * @else 170 * @brief 设置SPI的基础配置参数。 171 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 172 * @param [in] attr SPI的基础配置参数，参考 @ref spi_attr_t 。 173 * @retval ERRCODE_SUCC 成功。 174 * @retval Other 失败，参考 @ref errcode_t 。 175 * @endif 176 */ 177 errcode_t uapi_spi_set_attr(spi_bus_t bus, spi_attr_t *attr); 178 179 /** 180 * @if Eng 181 * @brief Get SPI basic configuration. 182 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 183 * @param [out] attr Basic configuration of SPI. For details, see @ref spi_attr_t. 184 * @retval ERRCODE_SUCC Success. 185 * @retval Other Failure. For details, For details, see @ref errcode_t. 186 * @else 187 * @brief 读取SPI的基础配置参数。 188 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 189 * @param [out] attr SPI的基础配置参数，参考 @ref spi_attr_t 。 190 * @retval ERRCODE_SUCC 成功。 191 * @retval Other 失败，参考 @ref errcode_t 。 192 * @endif 193 */ 194 errcode_t uapi_spi_get_attr(spi_bus_t bus, spi_attr_t *attr); 195 196 /** 197 * @if Eng 198 * @brief Set SPI extral configuration. 199 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 200 * @param [in] extra_attr Extral configuration of SPI. For details, see @ref spi_extra_attr_t. 201 * @retval ERRCODE_SUCC Success. 202 * @retval Other Failure. For details, see @ref errcode_t. 203 * @else 204 * @brief 设置SPI的高级配置参数。 205 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 206 * @param [in] extra_attr SPI的高级配置参数，参考 @ref spi_extra_attr_t 。 207 * @retval ERRCODE_SUCC 成功。 208 * @retval Other 失败，参考 @ref errcode_t 。 209 * @endif 210 */ 211 errcode_t uapi_spi_set_extra_attr(spi_bus_t bus, spi_extra_attr_t *extra_attr); 212 213 /** 214 * @if Eng 215 * @brief Get SPI extral configuration. 216 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 217 * @param [out] extra_attr Extral configuration of SPI. For details, see @ref spi_extra_attr_t. 218 * @retval ERRCODE_SUCC Success. 219 * @retval Other Failure. For details, see @ref errcode_t. 220 * @else 221 * @brief 读取SPI的高级配置参数。 222 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 223 * @param [out] extra_attr SPI的高级配置参数，参考 @ref spi_extra_attr_t 。 224 * @retval ERRCODE_SUCC 成功。 225 * @retval Other 失败，参考 @ref errcode_t 。 226 * @endif 227 */ 228 errcode_t uapi_spi_get_extra_attr(spi_bus_t bus, spi_extra_attr_t *extra_attr); 229 230 #if defined(CONFIG_SPI_SUPPORT_MASTER) && (CONFIG_SPI_SUPPORT_MASTER == 1) 231 /** 232 * @if Eng 233 * @brief Select slave device in master mode. 234 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 235 * @param [in] cs The slave need to select. 236 * @retval ERRCODE_SUCC Success. 237 * @retval Other Failure. For details, see @ref errcode_t. 238 * @else 239 * @brief Master模式下选择需要对通的Slave设备。 240 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 241 * @param [in] cs 被选中的Slave设备。 242 * @retval ERRCODE_SUCC 成功。 243 * @retval Other 失败，参考 @ref errcode_t 。 244 * @endif 245 */ 246 errcode_t uapi_spi_select_slave(spi_bus_t bus, spi_slave_t cs); 247 248 /** 249 * @if Eng 250 * @brief Write data from host to slave. There are two ways to write data from master to slave, 251 * one is manual switching mode, the other is automatic switching mode, 252 * and the two methods are statically configured. 253 * The manual switching method has the following three transmission modes, but cannot be used in the same bus at 254 * the same time. 255 * - Manually switching modes includes: 256 * - Polling mode 257 * - DMA mode 258 * - Interrupt mode 259 * - The automatic switching mode (automatically switching between the polling mode and the DMA mode by 260 * comparing the data length and the threshold value. For the threshold value, please refer to POLL and DMA 261 * automatic switching threshold setting in SPI KCONFIG) includes: 262 * - Polling mode: When the length of transmitted data is less than or equal to the threshold, it defaults 263 * to polling mode 264 * - DMA mode: When the length of the transmitted data exceeds the threshold, it automatically switches to 265 * DMA mode 266 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 267 * @param [in] data Pointer to transfer data. @ref spi_xfer_data_t. 268 * @param [in] timeout Timeout of the current transfer(In Polling mode it is polling count. In DMA mode it is 269 * timeout,unit ms. In Interrupt mode Param does not take effect). 270 * @retval ERRCODE_SUCC Success. 271 * @retval Other Failure. For details, see @ref errcode_t. 272 * @else 273 * @brief 将数据从主机写入到从机。有两种方式,一种是手动切换模式，另外一种是自动切换模式，两种方式是静态配置的。 274 * 手动切换方式一共有以下三种传输模式，但是不能在同一bus中同时使用。 275 * - 手动切换模式包括： 276 * - 轮询模式 277 * - DMA模式 278 * - 中断模式 279 * - 自动切换模式（通过比较数据长度和阈值的大小自动切换轮询模式与DMA模式, 阈值具体请参考SPI KCONFIG中POLL和DMA自动切换阈值设置）包括： 280 * - 轮询模式：当传输数据长度小于等于阈值时，默认为轮询模式 281 * - DMA模式：当传输数据长度大于阈值时，自动切换为DMA模式 282 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 283 * @param [in] data 数据传输指针，参考 @ref spi_xfer_data_t 。 284 * @param [in] timeout 当前传输的超时时间（轮询模式下为轮询次数；DMA模式为超时时间，单位：ms；中断模式参数不生效）。 285 * @retval ERRCODE_SUCC 成功。 286 * @retval Other 失败，参考 @ref errcode_t 。 287 * @endif 288 */ 289 errcode_t uapi_spi_master_write(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout); 290 291 /** 292 * @if Eng 293 * @brief Read data from slave. There are two ways to read data from slave to master, 294 * one is manual switching mode, the other is automatic switching mode, 295 * and the two methods are statically configured. 296 * The manual switching method has the following three transmission modes, but cannot be used in the same bus at 297 * the same time. 298 * - Manually switching modes includes: 299 * - Polling mode 300 * - DMA mode 301 * - Interrupt mode 302 * - The automatic switching mode (automatically switching between the polling mode and the DMA mode by 303 * comparing the data length and the threshold value. For the threshold value, please refer to POLL and DMA 304 * automatic switching threshold setting in SPI KCONFIG) includes: 305 * - Polling mode: When the length of transmitted data is less than or equal to the threshold, it defaults 306 * to polling mode 307 * - DMA mode: When the length of the transmitted data exceeds the threshold, it automatically switches to 308 * DMA mode 309 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 310 * @param [out] data Pointer to transfer data. @ref spi_xfer_data_t. 311 * @param [in] timeout Timeout of the current transfer(In Polling mode it is polling count. In DMA mode it is 312 * timeout,unit ms. In Interrupt mode Param does not take effect). 313 * @retval ERRCODE_SUCC Success. 314 * @retval Other Failure. For details, see @ref errcode_t. 315 * @else 316 * @brief 从slave读取数据。有两种方式,一种是手动切换模式，另外一种是自动切换模式，两种方式是静态配置的。 317 * 手动切换方式一共有以下三种传输模式，但是不能在同一bus中同时使用。 318 * - 手动切换模式包括： 319 * - 轮询模式 320 * - DMA模式 321 * - 中断模式 322 * - 自动切换模式（通过比较数据长度和阈值的大小自动切换轮询模式与DMA模式, 阈值具体请参考SPI KCONFIG中POLL和DMA自动切换阈值设置）包括： 323 * - 轮询模式：当传输数据长度小于等于阈值时，默认为轮询模式 324 * - DMA模式：当传输数据长度大于阈值时，自动切换为DMA模式 325 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 326 * @param [out] data 数据传输指针，参考 @ref spi_xfer_data_t 。 327 * @param [in] timeout 当前传输的超时时间（轮询模式下为轮询次数；DMA模式为超时时间，单位：ms；中断模式参数不生效）。 328 * @retval ERRCODE_SUCC 成功。 329 * @retval Other 失败，参考 @ref errcode_t 。 330 * @endif 331 */ 332 errcode_t uapi_spi_master_read(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout); 333 334 /** 335 * @if Eng 336 * @brief Write and read data in host. There are two ways to write and read data, 337 * one is manual switching mode, the other is automatic switching mode, 338 * and the two methods are statically configured. 339 * The manual switching method has the following three transmission modes, but cannot be used in the same bus at 340 * the same time. 341 * - Manually switching modes includes: 342 * - Polling mode 343 * - DMA mode 344 * - Interrupt mode 345 * - The automatic switching mode (automatically switching between the polling mode and the DMA mode by 346 * comparing the data length and the threshold value. For the threshold value, please refer to POLL and DMA 347 * automatic switching threshold setting in SPI KCONFIG) includes: 348 * - Polling mode: When the length of transmitted data is less than or equal to the threshold, it defaults 349 * to polling mode 350 * - DMA mode: When the length of the transmitted data exceeds the threshold, it automatically switches to 351 * DMA mode 352 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 353 * @param [in, out] data Pointer to transfer data. @ref spi_xfer_data_t. 354 * @param [in] timeout Timeout of the current transfer(In Polling mode it is polling count. In DMA mode it is 355 * timeout,unit ms. In Interrupt mode Param does not take effect). 356 * @retval ERRCODE_SUCC Success. 357 * @retval Other Failure. For details, see @ref errcode_t. 358 * @else 359 * @brief 主机写入和读取数据。有两种方式,一种是手动切换模式，另外一种是自动切换模式，两种方式是静态配置的。 360 * 手动切换方式一共有以下两种种传输模式，但是不能在同一bus中同时使用。 361 * - 手动切换模式包括： 362 * - 轮询模式 363 * - DMA模式 364 * - 中断模式 365 * - 自动切换模式（通过比较数据长度和阈值的大小自动切换轮询模式与DMA模式, 阈值具体请参考SPI KCONFIG中POLL和DMA自动切换阈值设置）包括： 366 * - 轮询模式：当传输数据长度小于等于阈值时，默认为轮询模式 367 * - DMA模式：当传输数据长度大于阈值时，自动切换为DMA模式 368 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 369 * @param [in, out] data 数据传输指针，参考 @ref spi_xfer_data_t 。 370 * @param [in] timeout 当前传输的超时时间（轮询模式下为轮询次数；DMA模式为超时时间，单位：ms；中断模式参数不生效）。 371 * @retval ERRCODE_SUCC 成功。 372 * @retval Other 失败，参考 @ref errcode_t 。 373 * @endif 374 */ 375 errcode_t uapi_spi_master_writeread(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout); 376 #endif /* CONFIG_SPI_SUPPORT_MASTER */ 377 378 #if defined(CONFIG_SPI_SUPPORT_SLAVE) && (CONFIG_SPI_SUPPORT_SLAVE == 1) 379 /** 380 * @if Eng 381 * @brief Write data from slave to host. There are two ways to write data from slave to master, 382 * one is manual switching mode, the other is automatic switching mode, 383 * and the two methods are statically configured. 384 * The manual switching method has the following three transmission modes, but cannot be used in the same bus at 385 * the same time. 386 * - Manually switching modes includes: 387 * - Polling mode 388 * - DMA mode 389 * - Interrupt mode 390 * - The automatic switching mode (automatically switching between the polling mode and the DMA mode by 391 * comparing the data length and the threshold value. For the threshold value, please refer to POLL and DMA 392 * automatic switching threshold setting in SPI KCONFIG) includes: 393 * - Polling mode: When the length of transmitted data is less than or equal to the threshold, it defaults 394 * to polling mode 395 * - DMA mode: When the length of the transmitted data exceeds the threshold, it automatically switches to 396 * DMA mode the threshold 397 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 398 * @param [in] data Pointer to transfer data. @ref spi_xfer_data_t. 399 * @param [in] timeout Timeout of the current transfer(In Polling mode it is polling count. In DMA mode it is 400 * timeout,unit ms. In Interrupt mode Param does not take effect). 401 * @retval ERRCODE_SUCC Success. 402 * @retval Other Failure. For details, see @ref errcode_t. 403 * @else 404 * @brief 从机向主机写入数据。有两种方式,一种是手动切换模式，另外一种是自动切换模式，两种方式是静态配置的。 405 * 手动切换方式一共有以下三种传输模式，但是不能在同一bus中同时使用。 406 * - 手动切换模式包括： 407 * - 轮询模式 408 * - DMA模式 409 * - 中断模式 410 * - 自动切换模式（通过比较数据长度和阈值的大小自动切换轮询模式与DMA模式, 阈值具体请参考SPI KCONFIG中POLL和DMA自动切换阈值设置）包括： 411 * - 轮询模式：当传输数据长度小于等于阈值时，默认为轮询模式 412 * - DMA模式：当传输数据长度大于阈值时，自动切换为DMA模式 413 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 414 * @param [in] data 数据传输指针，参考 @ref spi_xfer_data_t 。 415 * @param [in] timeout 当前传输的超时时间（轮询模式下为轮询次数；DMA模式为超时时间，单位：ms；中断模式参数不生效）。 416 * @retval ERRCODE_SUCC 成功。 417 * @retval Other 失败，参考 @ref errcode_t 。 418 * @endif 419 */ 420 errcode_t uapi_spi_slave_write(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout); 421 422 /** 423 * @if Eng 424 * @brief Read data from host. There are two ways to read data from master to slave, 425 * one is manual switching mode, the other is automatic switching mode, 426 * and the two methods are statically configured. 427 * The manual switching method has the following three transmission modes, but cannot be used in the same bus at 428 * the same time. 429 * - Manually switching modes includes: 430 * - Polling mode 431 * - DMA mode 432 * - Interrupt mode 433 * - The automatic switching mode (automatically switching between the polling mode and the DMA mode by 434 * comparing the data length and the threshold value. For the threshold value, please refer to POLL and DMA 435 * automatic switching threshold setting in SPI KCONFIG) includes: 436 * - Polling mode: When the length of transmitted data is less than or equal to the threshold, it defaults 437 * to polling mode 438 * - DMA mode: When the length of the transmitted data exceeds the threshold, it automatically switches to 439 * DMA mode 440 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 441 * @param [out] data Pointer to transfer data. @ref spi_xfer_data_t. 442 * @param [in] timeout Timeout of the current transfer(In Polling mode it is polling count. In DMA mode it is 443 * timeout,unit ms. In Interrupt mode Param does not take effect). 444 * @retval ERRCODE_SUCC Success. 445 * @retval Other Failure. For details, see @ref errcode_t. 446 * @else 447 * @brief 从主机读取数据。有两种方式,一种是手动切换模式，另外一种是自动切换模式，两种方式是静态配置的。 448 * 手动切换方式一共有以下三种传输模式，但是不能在同一bus中同时使用。 449 * - 手动切换模式包括： 450 * - 轮询模式 451 * - DMA模式 452 * - 中断模式 453 * - 自动切换模式（通过比较数据长度和阈值的大小自动切换轮询模式与DMA模式, 阈值具体请参考SPI KCONFIG中POLL和DMA自动切换阈值设置）包括： 454 * - 轮询模式：当传输数据长度小于等于阈值时，默认为轮询模式 455 * - DMA模式：当传输数据长度大于阈值时，自动切换为DMA模式 456 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 457 * @param [out] data 数据传输指针，参考 @ref spi_xfer_data_t 。 458 * @param [in] timeout 当前传输的超时时间（轮询模式下为轮询次数；DMA模式为超时时间，单位：ms；中断模式参数不生效）。 459 * @retval ERRCODE_SUCC 成功。 460 * @retval Other 失败，参考 @ref errcode_t 。 461 * @endif 462 */ 463 errcode_t uapi_spi_slave_read(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout); 464 465 /** 466 * @if Eng 467 * @brief Write and read data from host. There are two ways to write and read data, 468 * one is manual switching mode, the other is automatic switching mode, 469 * and the two methods are statically configured. 470 * The manual switching method has the following three transmission modes, but cannot be used in the same bus at 471 * the same time. 472 * - Manually switching modes includes: 473 * - Polling mode 474 * - DMA mode 475 * - Interrupt mode 476 * - The automatic switching mode (automatically switching between the polling mode and the DMA mode by 477 * comparing the data length and the threshold value. For the threshold value, please refer to POLL and DMA 478 * automatic switching threshold setting in SPI KCONFIG) includes: 479 * - Polling mode: When the length of transmitted data is less than or equal to the threshold, it defaults 480 * to polling mode 481 * - DMA mode: When the length of the transmitted data exceeds the threshold, it automatically switches to 482 * DMA mode 483 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 484 * @param [in, out] data Pointer to transfer data. @ref spi_xfer_data_t. 485 * @param [in] timeout Timeout of the current transfer(In Polling mode it is polling count. In DMA mode it is 486 * timeout,unit ms. In Interrupt mode Param does not take effect). 487 * @retval ERRCODE_SUCC Success. 488 * @retval Other Failure. For details, see @ref errcode_t. 489 * @else 490 * @brief 从机写入和读取数据。有两种方式,一种是手动切换模式，另外一种是自动切换模式，两种方式是静态配置的。 491 * 手动切换方式一共有以下两种种传输模式，但是不能在同一bus中同时使用。 492 * - 手动切换模式包括： 493 * - 轮询模式 494 * - DMA模式 495 * - 中断模式 496 * - 自动切换模式（通过比较数据长度和阈值的大小自动切换轮询模式与DMA模式, 阈值具体请参考SPI KCONFIG中POLL和DMA自动切换阈值设置）包括： 497 * - 轮询模式：当传输数据长度小于等于阈值时，默认为轮询模式 498 * - DMA模式：当传输数据长度大于阈值时，自动切换为DMA模式 499 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 500 * @param [in, out] data 数据传输指针，参考 @ref spi_xfer_data_t 。 501 * @param [in] timeout 当前传输的超时时间（轮询模式下为轮询次数；DMA模式为超时时间，单位：ms；中断模式参数不生效）。 502 * @retval ERRCODE_SUCC 成功。 503 * @retval Other 失败，参考 @ref errcode_t 。 504 * @endif 505 */ 506 errcode_t uapi_spi_slave_writeread(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout); 507 #endif /* CONFIG_SPI_SUPPORT_SLAVE */ 508 509 #if !defined(CONFIG_SPI_SUPPORT_POLL_AND_DMA_AUTO_SWITCH) 510 #if defined(CONFIG_SPI_SUPPORT_DMA) && (CONFIG_SPI_SUPPORT_DMA == 1) 511 /** 512 * @if Eng 513 * @brief Enable/disable data transfer function in DMA mode. 514 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 515 * @param [in] en Enable/disable data transfer 516 * @param [in] dma_cfg Pointer to the configuration structure of DMA. @ref spi_dma_config_t. 517 * If want to set the mode to disable, configuration this parameter to NULL. 518 * @retval ERRCODE_SUCC Success. 519 * @retval Other Failure. For details, see @ref errcode_t. 520 * @else 521 * @brief 使能/去使能DMA模式下SPI传输。 522 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 523 * @param [in] en 是否使能DMA传输。 524 * @param [in] dma_cfg DMA配置结构体指针，参考 @ref spi_dma_config_t 。如果模式为去使能，这里配置为NULL。 525 * @retval ERRCODE_SUCC 成功。 526 * @retval Other 失败，参考 @ref errcode_t 。 527 * @endif 528 */ 529 errcode_t uapi_spi_set_dma_mode(spi_bus_t bus, bool en, const spi_dma_config_t *dma_cfg); 530 #endif /* CONFIG_SPI_SUPPORT_DMA */ 531 532 #if defined(CONFIG_SPI_SUPPORT_INTERRUPT) && (CONFIG_SPI_SUPPORT_INTERRUPT == 1) 533 /** 534 * @if Eng 535 * @brief SPI Transmission Callback function to be called when the RX condition registered on 536 @ref uapi_spi_set_irq_mode is invoked. 537 * @note This callback is invoked in an interrupt context. 538 * @param buffer Pointer to the buffer to stored the data to be write. The value is given from data write interface. 539 * @param length Length of the data that has been write. The value is given from data write interface. 540 * @else 541 * @brief SPI发送数据的回调函数，通过 @ref uapi_spi_set_irq_mode 注册到驱动中。 542 * @note 这个函数是在中断上下文中执行的。 543 * @param buffer 指向缓冲区的指针，用于存储写入的数据。由写接口函数的参数传入。 544 * @param length 写入的数据长度。由写接口函数的参数传入。 545 * @endif 546 */ 547 typedef void (*spi_tx_callback_t)(const void *buffer, uint32_t length); 548 549 /** 550 * @if Eng 551 * @brief SPI Transmission Callback function to be called when the RX condition registered on 552 @ref uapi_spi_set_irq_mode is invoked or the error is happened. 553 * @note This callback is invoked in an interrupt context. 554 * @param buffer Pointer to the buffer to stored the data to be read. The value is given from data read interface. 555 * @param length Length of the data that has been read. The value is given from data read interface. 556 * @param error Indicates if there is error on the SPI lines or not. Error lists: 557 * - RX overflow error 558 * - RX underflow error 559 * @else 560 * @brief SPI接收数据的回调函数，通过 @ref uapi_spi_set_irq_mode 注册到驱动中。 561 * @note 这个函数是在中断上下文中执行的。 562 * @param buffer 指向缓冲区的指针，用于存储要读取的数据。由读取接口函数的参数传入。 563 * @param length 读取到的数据长度。由读取接口函数的参数传入。 564 * @param error 表示SPI传输是否存在错误，错误情况： 565 * - RX上限溢出错误 566 * - RX下限溢出错误 567 * @endif 568 */ 569 typedef void (*spi_rx_callback_t)(const void *buffer, uint32_t length, bool error); 570 571 /** 572 * @if Eng 573 * @brief Set whether to use the interrupt mode to transfer data in master mode. 574 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t 575 * @param [in] irq_en Whether to use the interrupt mode. 576 * @param [in] rx_callback Receive callback to called when data read is completed. 577 * @param [in] tx_callback Transmit callback to called when data write is completed. 578 * @retval ERRCODE_SUCC Success. 579 * @retval Other Failure. For details, see @ref errcode_t. 580 * @else 581 * @brief 设置是否使用中断模式在主机模式下传输数据。 582 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 583 * @param [in] irq_en 是否使用中断模式。 584 * @param [in] rx_callback 接收数据完成时的回调函数。 585 * @param [in] tx_callback 数据发送完成时的回调函数。 586 * @retval ERRCODE_SUCC 成功。 587 * @retval Other 失败，参考 @ref errcode_t 。 588 * @endif 589 */ 590 errcode_t uapi_spi_set_irq_mode(spi_bus_t bus, bool irq_en, spi_rx_callback_t rx_callback, 591 spi_tx_callback_t tx_callback); 592 #endif /* CONFIG_SPI_SUPPORT_INTERRUPT */ 593 #endif /* NOT CONFIG_SPI_SUPPORT_POLL_AND_DMA_AUTO_SWITCH */ 594 595 #if defined(CONFIG_SPI_SUPPORT_LOOPBACK) && (CONFIG_SPI_SUPPORT_LOOPBACK == 1) 596 /** 597 * @if Eng 598 * @brief Whether to set to loopback test mode. 599 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 600 * @param [in] loopback_en Loopback mode enable/disable. 601 * @retval ERRCODE_SUCC Success. 602 * @retval Other Failure. For details, see @ref errcode_t. 603 * @else 604 * @brief 是否设置为环回测试模式。 605 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 606 * @param [in] loopback_en 环回模式使能/去使能。 607 * @retval ERRCODE_SUCC 成功。 608 * @retval Other 失败，参考 @ref errcode_t 。 609 * @endif 610 */ 611 errcode_t uapi_spi_set_loop_back_mode(spi_bus_t bus, bool loopback_en); 612 #endif /* CONFIG_SPI_SUPPORT_LOOPBACK */ 613 614 #if defined(CONFIG_SPI_SUPPORT_CRC) && (CONFIG_SPI_SUPPORT_CRC == 1) 615 /** 616 * @if Eng 617 * @brief SPI CRC configuration parameters. 618 * @else 619 * @brief SPI CRC 配置参数。 620 * @endif 621 */ 622 typedef struct spi_crc_config { 623 uint32_t tx_crc_len; /*!< @if Eng Send a crc virified data before this length. 624 @else 逻辑在此长度之前发送CRC验证数据。@endif */ 625 uint32_t rx_crc_len; /*!< @if Eng Logic receive a crc virified data before this length. 626 @else 逻辑在此长度之前接收CRC验证数据。@endif */ 627 uint32_t tx_crc_ini; /*!< @if Eng Tx init val configuration. 628 @else tx初始化值配置。@endif */ 629 uint32_t rx_crc_ini; /*!< @if Eng Rx init val configuration. 630 @else rx初始化值配置。@endif */ 631 uint32_t tx_crc_poly; /*!< @if Eng Tx polynomial configuration. 632 @else tx多项式配置。@endif */ 633 uint32_t rx_crc_poly; /*!< @if Eng Rx polynomial configuration. 634 @else tx多项式配置。@endif */ 635 uint32_t tx_crc_xor_out; /*!< @if Eng Tx result XOR configuration. 636 @else tx结果异或配置。@endif */ 637 uint32_t rx_crc_xor_out; /*!< @if Eng Rx result XOR configuration. 638 @else rx结果异或配置。@endif */ 639 bool tx_crc_refin; /*!< @if Eng tx Input value inversion configuration. 640 @else tx输入值翻转配置。@endif */ 641 bool tx_crc_refout; /*!< @if Eng tx Output value inversion configuration. 642 @else tx输出值翻转配置。@endif */ 643 bool rx_crc_refin; /*!< @if Eng rx Input value inversion configuration. 644 @else rx输入值翻转配置。@endif */ 645 bool rx_crc_refout; /*!< @if Eng rx Output value inversion configuration. 646 @else rx输出值翻转配置。@endif */ 647 } spi_crc_config_t; 648 649 /** 650 * @if Eng 651 * @brief SPI CRC error callback. 652 * @else 653 * @brief SPI CRC错误处理回调函数。 654 * @endif 655 */ 656 typedef void (*spi_crc_err_callback_t)(spi_bus_t bus); 657 658 /** 659 * @if Eng 660 * @brief Set SPI tx and rx crc mode. 661 * @param [in] bus The SPI bus. For details, see @ref spi_bus_t. 662 * @param [in] crc_config CRC configuration parameters. 663 * @param [in] cb Ccallback function for CRC check errors. 664 * @retval ERRCODE_SUCC Success. 665 * @retval Other Failure. For details, see @ref errcode_t. 666 * @else 667 * @brief 设置SPI发送和接收CRC模式。 668 * @param [in] bus 指定的SPI接口，参考 @ref spi_bus_t 。 669 * @param [in] crc_config 配置SPI的crc参数。 670 * @param [in] cb crc检验错误回调函数。 671 * @retval ERRCODE_SUCC 成功。 672 * @retval Other 失败，参考 @ref errcode_t 。 673 * @endif 674 */ 675 errcode_t uapi_spi_set_crc_mode(spi_bus_t bus, const spi_crc_config_t *crc_config, spi_crc_err_callback_t cb); 676 #endif /* CONFIG_SPI_SUPPORT_CRC */ 677 678 #if defined(CONFIG_SPI_SUPPORT_LPM) 679 /** 680 * @if Eng 681 * @brief Suspend all of the SPI channels. 682 * @param [in] arg Argument for suspend. 683 * @retval ERRCODE_SUCC Success. 684 * @retval Other Failure. For details, see @ref errcode_t. 685 * @else 686 * @brief 挂起所有SPI通道。 687 * @param [in] arg 挂起所需要的参数。 688 * @retval ERRCODE_SUCC 成功。 689 * @retval Other 失败，参考 @ref errcode_t 。 690 * @endif 691 */ 692 errcode_t uapi_spi_suspend(uintptr_t arg); 693 694 /** 695 * @if Eng 696 * @brief Resume all of the SPI channels. 697 * @param [in] arg Argument for resume. 698 * @retval ERRCODE_SUCC Success. 699 * @retval Other Failure. For details, see @ref errcode_t. 700 * @else 701 * @brief 恢复所有SPI通道。 702 * @param [in] arg 恢复所需要的参数。 703 * @retval ERRCODE_SUCC 成功。 704 * @retval Other 失败，参考 @ref errcode_t 。 705 * @endif 706 */ 707 errcode_t uapi_spi_resume(uintptr_t arg); 708 #endif 709 710 /** 711 * @} 712 */ 713 714 #ifdef __cplusplus 715 #if __cplusplus 716 } 717 #endif /* __cplusplus */ 718 #endif /* __cplusplus */ 719 720 #endif