1 /** 2 * @file hi_spi.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 * 描述：SPI SDK APIs. CNcomment:SPI SDK调用接口。CNend 18 * @li Supports synchronous serial communication with external devices as the master or slave. 19 CNcomment:支持作为Master或Slave与外部设备进行同步串行通信。CNend 20 * @li The SPI working reference clock is 160 MHz, the maximum output of Master SPI_CLK is 40 MHz, and the maximum 21 * output of Slave SPI_CLK is 20 MHz. CNcomment:SPI工作参考时钟为160 MHz， 22 作为Master SPI_CLK最大输出为40MHz，作为Slave SPI_CLK最大支持20MHz。CNend 23 * @li Provides two SPIs. The SPI0 provides one TX/RX FIFO for the 16bit×256, and the SPI1 provides one TX/RX 24 * FIFO for the 16bit×64. CNcomment:提供两路SPI，SPI0提供16bit×256的TX/RX FIFO各一个, 25 SPI1提供16bit×64的TX/RX FIFO各一个。CNend 26 * @li Only full-duplex communication is supported. When the half-duplex mode is used, the fixed value is sent. 27 * When the half-duplex mode is used, the data in the FIFO is discarded. 28 CNcomment:只支持全双工通信，半双工收时发送固定数值，半双工收时丢弃FIFO中的数据。CNend \n 29 */ 30 31 /** 32 * @defgroup iot_spi SPI 33 * @ingroup drivers 34 */ 35 36 #ifndef __HI_SPI_H__ 37 #define __HI_SPI_H__ 38 #include <hi_types.h> 39 40 /** 41 * @ingroup iot_spi 42 * 43 * Channel ID, [0,1]. CNcomment:通道ID：0~1。CNend 44 */ 45 typedef enum { 46 HI_SPI_ID_0 = 0, 47 HI_SPI_ID_1, 48 } hi_spi_idx; 49 50 /** 51 * @ingroup iot_spi 52 * 53 * Communication polarity.CNcomment:通信极性。CNend 54 */ 55 typedef enum { 56 HI_SPI_CFG_CLOCK_CPOL_0, /**< Polarity 0.CNcomment:极性0 CNend */ 57 HI_SPI_CFG_CLOCK_CPOL_1, /**< Polarity 1.CNcomment:极性1 CNend */ 58 } hi_spi_cfg_clock_cpol; 59 60 /** 61 * @ingroup iot_spi 62 * 63 * Communication phase.CNcomment:通信相位。CNend 64 */ 65 typedef enum { 66 HI_SPI_CFG_CLOCK_CPHA_0, /**< Phase 0.CNcomment:相位0 CNend */ 67 HI_SPI_CFG_CLOCK_CPHA_1, /**< Phase 1.CNcomment:相位1 CNend */ 68 } hi_spi_cfg_clock_cpha; 69 70 /** 71 * @ingroup iot_spi 72 * 73 * Communication protocol type. CNcomment:通信协议类型。CNend 74 */ 75 typedef enum { 76 HI_SPI_CFG_FRAM_MODE_MOTOROLA, /**< Motorola protocol.CNcomment:摩托罗拉协议CNend */ 77 HI_SPI_CFG_FRAM_MODE_TI, /**< Texas Instruments protocol.CNcomment:德州仪器协议CNend */ 78 HI_SPI_CFG_FRAM_MODE_MICROWIRE, /**< Microwire protocol.CNcomment:Microware协议CNend */ 79 } hi_spi_cfg_fram_mode; 80 81 /** 82 * @ingroup iot_spi 83 * 84 * Communication bit width, that is, number of valid bits in each frame.CNcomment:通信位宽， 85 每帧内的有效bit数。CNend 86 */ 87 typedef enum { 88 HI_SPI_CFG_DATA_WIDTH_E_4BIT = 0x3, /**< The bit width is 4 bits.CNcomment:位宽为4bit CNend */ 89 HI_SPI_CFG_DATA_WIDTH_E_5BIT, /**< The bit width is 5 bits.CNcomment:位宽为5bit CNend */ 90 HI_SPI_CFG_DATA_WIDTH_E_6BIT, /**< The bit width is 6 bits.CNcomment:位宽为6bit CNend */ 91 HI_SPI_CFG_DATA_WIDTH_E_7BIT, /**< The bit width is 7 bits.CNcomment:位宽为7bit CNend */ 92 HI_SPI_CFG_DATA_WIDTH_E_8BIT, /**< The bit width is 8 bits.CNcomment:位宽为8bit CNend */ 93 HI_SPI_CFG_DATA_WIDTH_E_9BIT, /**< The bit width is 9 bits.CNcomment:位宽为9bit CNend */ 94 HI_SPI_CFG_DATA_WIDTH_E_10BIT, /**< The bit width is 10 bits.CNcomment:位宽为10bit CNend */ 95 HI_SPI_CFG_DATA_WIDTH_E_11BIT, /**< The bit width is 11 bits.CNcomment:位宽为11bit CNend */ 96 HI_SPI_CFG_DATA_WIDTH_E_12BIT, /**< The bit width is 12 bits.CNcomment:位宽为12bit CNend */ 97 HI_SPI_CFG_DATA_WIDTH_E_13BIT, /**< The bit width is 13 bits.CNcomment:位宽为13bit CNend */ 98 HI_SPI_CFG_DATA_WIDTH_E_14BIT, /**< The bit width is 14 bits.CNcomment:位宽为14bit CNend */ 99 HI_SPI_CFG_DATA_WIDTH_E_15BIT, /**< The bit width is 15 bits.CNcomment:位宽为15bit CNend */ 100 HI_SPI_CFG_DATA_WIDTH_E_16BIT, /**< The bit width is 16 bits.CNcomment:位宽为16bit CNend */ 101 } hi_spi_cfg_data_width; 102 103 /** 104 * @ingroup iot_spi 105 * 106 * Communication parameter: big-endian and little-endian transmission of each frame. 107 CNcomment:通信参数：每帧的传输大小端。CNend 108 */ 109 typedef enum { 110 HI_SPI_CFG_ENDIAN_LITTLE, /**< Little-endian transmission.CNcomment:小端传输CNend */ 111 HI_SPI_CFG_ENDIAN_BIG, /**< Big-endian transmission.CNcomment:大端传输CNend */ 112 } hi_spi_cfg_endian; 113 114 /** 115 * @ingroup iot_spi 116 * @brief Type of the SPI callback function.CNcomment:SPI回调函数的类型。CNend 117 * 118 * @par 描述: 119 * Type of the SPI callback function.CNcomment:SPI回调函数的类型。CNend 120 * 121 * @attention None 122 * 123 * @param None 124 * 125 * @retval None 126 * 127 * @par 依赖: 128 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 129 * @see None 130 */ 131 typedef hi_void (*hi_spi_usr_func)(hi_void); 132 133 /** 134 * @ingroup iot_spi 135 * 136 * Data communication parameter.CNcomment:数据通信参数。CNend 137 */ 138 typedef struct { 139 hi_u32 cpol : 1; /**< Communication polarity, type hi_spi_cfg_clock_cpol.CNcomment:通信极性，类型 140 为hi_spi_cfg_clock_cpol。CNend */ 141 hi_u32 cpha : 1; /**< Communication phase, type hi_spi_cfg_clock_cpha.CNcomment:通信相位，类型 142 为hi_spi_cfg_clock_cpha。CNend */ 143 hi_u32 fram_mode : 2; /**< Communication protocol type, type hi_spi_cfg_fram_mode.CNcomment:通信协议类型，类型 144 为hi_spi_cfg_fram_mode。CNend */ 145 hi_u32 data_width : 4; /**< Communication bit width, type hi_spi_cfg_data_width.CNcomment:通信位宽，类型为 146 hi_spi_cfg_data_width。 CNend */ 147 hi_u32 endian : 1; /**< Big-endian and little-endian, type hi_spi_cfg_endian.CNcomment:大小端，类型为 148 hi_spi_cfg_endian。CNend */ 149 hi_u32 pad : 23; /**< Reserve bits.CNcomment:保留位 CNend */ 150 hi_u32 freq; /**< Communication frequency, ranges 2460Hz-40MHz.CNcomment:通信频率，取值范围 151 2460Hz-40MHz。CNend */ 152 } hi_spi_cfg_basic_info; 153 154 /** 155 * @ingroup iot_spi 156 * 157 * Data communication parameter.CNcomment:主从设备设置。CNend 158 */ 159 typedef struct { 160 hi_u32 is_slave : 1; 161 hi_u32 pad : 31; 162 } hi_spi_cfg_init_param; 163 /** 164 * @ingroup iot_spi 165 * @brief TX interface for the SPI slave mode.CNcomment:SPI从模式发送接口。CNend 166 * 167 * @par 描述: 168 * TX interface for the SPI slave mode.CNcomment:SPI从模式发送接口。CNend 169 * 170 * @attention None 171 * 172 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 173 * @param write_data [IN] type #hi_pvoid，TX data pointer.CNcomment;发送数据指针。CNend 174 * @param byte_len [IN] type #hi_u32，length of the target data to be sent (unit: byte). 175 CNcomment:发送数据长度（单位：byte）。CNend 176 * @param time_out_ms [IN] type #hi_u32，wait timeout period.CNcomment:超时时间。CNend 177 * 178 * @retval #0 Success 179 * @retval #Other Failure. For details, see hi_errno.h. 180 * @par 依赖: 181 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 182 * @see None 183 */ 184 hi_u32 hi_spi_slave_write(hi_spi_idx spi_id, hi_pvoid write_data, hi_u32 byte_len, hi_u32 time_out_ms); 185 186 /** 187 * @ingroup iot_spi 188 * @brief RX interface for the SPI slave mode.CNcomment:SPI从模式接收接口。CNend 189 * 190 * @par 描述: 191 * RX interface for the SPI slave mode.CNcomment:SPI从模式接收接口。CNend 192 * 193 * @attention None 194 * 195 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 196 * @param read_data [OUT] type #hi_pvoid，RX data pointer.CNcomment:接收数据指针。CNend 197 * @param byte_len [IN] type #hi_u32，length of the target data to be received (unit: byte). 198 CNcomment:接收数据长度（单位：byte）。CNend 199 * @param time_out_ms [IN] type #hi_u32，wait timeout period.CNcomment:超时时间。CNend 200 * 201 * @retval #0 Success 202 * @retval #Other Failure. For details, see hi_errno.h. 203 * @par 依赖: 204 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 205 * @see None 206 */ 207 hi_u32 hi_spi_slave_read(hi_spi_idx spi_id, hi_pvoid read_data, hi_u32 byte_len, hi_u32 time_out_ms); 208 209 /** 210 * @ingroup iot_spi 211 * @brief Half-duplex TX interface for the SPI master mode.CNcomment:SPI主模式半双工发送接口。CNend 212 * 213 * @par 描述: 214 * Half-duplex TX interface for the SPI master mode.CNcomment: SPI主模式半双工发送接口。CNend 215 * 216 * @attention None 217 * 218 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 219 * @param write_data [IN] type #hi_pvoid，TX data pointer.CNcomment;发送数据指针。CNend 220 * @param byte_len [IN] type #hi_u32，length of the target data to be sent (unit: byte). 221 CNcomment:发送数据长度（单位：byte）。CNend 222 * 223 * @retval #0 Success 224 * @retval #Other Failure. For details, see hi_errno.h. 225 * @par 依赖: 226 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 227 * @see None 228 */ 229 hi_u32 hi_spi_host_write(hi_spi_idx spi_id, hi_pvoid write_data, hi_u32 byte_len); 230 231 /** 232 * @ingroup iot_spi 233 * @brief Half-duplex RX interface for the SPI master mode.CNcomment:SPI主模式半双工接收接口。CNend 234 * 235 * @par 描述: 236 * Half-duplex RX interface for the SPI master mode.CNcomment:SPI主模式半双工接收接口。CNend 237 * 238 * @attention None 239 * 240 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 241 * @param read_data [OUT] type #hi_pvoid，RX data pointer.CNcomment:接收数据指针。CNend 242 * @param byte_len [IN] type #hi_u32，length of the target data to be received (unit: byte). 243 CNcomment:接收数据长度（单位：byte）。CNend 244 * 245 * @retval #0 Success 246 * @retval #Other Failure. For details, see hi_errno.h. 247 * @par 依赖: 248 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 249 * @see None 250 */ 251 hi_u32 hi_spi_host_read(hi_spi_idx spi_id, hi_pvoid read_data, hi_u32 byte_len); 252 253 /** 254 * @ingroup iot_spi 255 * @brief Full-duplex TX/RX interface for the SPI master mode.CNcomment:SPI主模式全双工收发接口。CNend 256 * 257 * @par 描述: 258 * Full-duplex TX/RX interface for the SPI master mode.CNcomment:SPI主模式全双工收发接口。CNend 259 * 260 * @attention None. 261 * 262 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 263 * @param write_data [IN] type #hi_pvoid，TX data pointer.CNcomment;发送数据指针。CNend 264 * @param read_data [OUT] type #hi_pvoid，RX data pointer.CNcomment:接收数据指针。CNend 265 * @param byte_len [IN] type #hi_u32，length of the target data to be received (unit: byte). 266 CNcomment:接收数据长度（单位：byte）。CNend 267 * 268 * @retval #0 Success 269 * @retval #Other Failure. For details, see hi_errno.h. 270 * @par 依赖: 271 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 272 * @see None 273 */ 274 hi_u32 hi_spi_host_writeread(hi_spi_idx spi_id, hi_pvoid write_data, hi_pvoid read_data, hi_u32 byte_len); 275 276 277 /** 278 * @ingroup iot_spi 279 * @brief Configures the SPI parameter.CNcomment:配置SPI参数。CNend 280 * 281 * @par 描述: 282 * Configures the SPI parameter.CNcomment:配置SPI参数。CNend 283 * 284 * @attention None 285 * 286 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 287 * @param param [IN] type #hi_spi_cfg_basic_info，SPI parameters.CNcomment:SPI参数。CNend 288 * 289 * @retval #0 Success 290 * @retval #Other Failure. For details, see hi_errno.h. 291 * @par 依赖: 292 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 293 * @see None 294 */ 295 hi_u32 hi_spi_set_basic_info(hi_spi_idx spi_id, const hi_spi_cfg_basic_info *param); 296 297 /** 298 * @ingroup iot_spi 299 * @brief Initializes the SPI module.CNcomment:SPI模块初始化。CNend 300 * 301 * @par 描述: 302 * Initializes the SPI module.CNcomment:SPI模块初始化。CNend 303 * 304 * @attention To initialize the SPI module, the user needs to perform the initial configuration on the SPI 305 * information as follows:CNcomment:对SPI模块初始化，用户需要对SPI如下信息进行初始配置：CNend 306 * @li Clear spi_ctrl to 0.CNcomment:spi_ctrl进行清空为0操作。CNend 307 * @li Configure the master/slave mode. CNcomment:配置SPI[id]的主/从模式。CNend 308 * @li Configure the transfer parameters.CNcomment:配置SPI[id]的传输参数。CNend 309 * 310 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 311 * @param init_param [IN] type #hi_spi_cfg_init_param，initialize as a slave device.CNcomment:是否做为从设备。CNend 312 * @param param [IN] type #const hi_spi_cfg_basic_info*，configure parameters.CNcomment:初始化SPI设备参数。CNend 313 * 314 * @retval #0 Success 315 * @retval #Other Failure. For details, see hi_errno.h. 316 * @par 依赖: 317 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 318 * @see None 319 */ 320 hi_u32 hi_spi_init(hi_spi_idx spi_id, hi_spi_cfg_init_param init_param, const hi_spi_cfg_basic_info *param); 321 322 /** 323 * @ingroup iot_spi 324 * @brief Deinitializes the SPI module.CNcomment:SPI模块去初始化。CNend 325 * 326 * @par 描述: 327 * Deinitializes the SPI module.CNcomment:SPI模块去初始化。CNend 328 * 329 * @attention None 330 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 331 * 332 * @retval #0 Success 333 * @retval #Other Failure. For details, see hi_errno.h. 334 * @par 依赖: 335 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 336 * @see None 337 */ 338 hi_u32 hi_spi_deinit(hi_spi_idx spi_id); 339 340 /** 341 * @ingroup iot_spi 342 * @brief Set a master spi to use irq mode.CNcomment:设置是否使用中断方式传输数据。CNend 343 * 344 * @par 描述: 345 * Set a master spi to use irq mode.CNcomment:设置是否使用中断方式传输数据。CNend 346 * 347 * @attention None 348 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 349 * @param irq_en [IN] type #hi_bool，enable irq. CNcomment:是否使用中断方式。CNend 350 * 351 * @retval #0 Success 352 * @retval #Other Failure. For details, see hi_errno.h. 353 * @par 依赖: 354 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 355 * @see None 356 */ 357 hi_u32 hi_spi_set_irq_mode(hi_spi_idx id, hi_bool irq_en); 358 359 /** 360 * @ingroup iot_spi 361 * @brief Set a master spi to use dma mode.CNcomment:设置slave 模式下是否使用DMA方式传输数据。CNend 362 * 363 * @par 描述: 364 * Set a master spi to use dma mode.CNcomment:设置slave模式下是否使用DMA方式传输数据。CNend 365 * 366 * @attention None 367 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 368 * @param dma_en [IN] type #hi_bool，enable dma. CNcomment:是否使用DMA方式。CNend 369 * 370 * @retval #0 Success 371 * @retval #Other Failure. For details, see hi_errno.h. 372 * @par 依赖: 373 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 374 * @see None 375 */ 376 hi_u32 hi_spi_set_dma_mode(hi_spi_idx id, hi_bool dma_en); 377 378 /** 379 * @ingroup iot_spi 380 * @brief Register a user to prepare or restore function.CNcomment:注册用户准备/恢复函数。CNend 381 * 382 * @par 描述: 383 * Register a user to prepare or restore function.CNcomment:注册用户准备/恢复函数。CNend 384 * 385 * @attention None 386 * @param spi_id [IN] type #hi_spi_idx，SPI ID。 387 * @param prepare_f [IN] type #hi_spi_usr_func，user prepare function.CNcomment:用户准备函数。CNend 388 * @param restore_f [IN] type #hi_spi_usr_func，user restore fucntion.CNcomment:用户恢复函数。CNend 389 * 390 * @retval #0 Success 391 * @retval #Other Failure. For details, see hi_errno.h. 392 * @par 依赖: 393 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 394 * @see None 395 */ 396 hi_u32 hi_spi_register_usr_func(hi_spi_idx id, hi_spi_usr_func prepare_f, hi_spi_usr_func restore_f); 397 398 /** 399 * @ingroup iot_spi 400 * @brief Set whether to loopback test mode.CNcomment:设置是否为回环测试模式。CNend 401 * 402 * @par 描述: 403 * Set whether to loopback test mode.CNcomment:设置是否为回环测试模式。CNend 404 * 405 * @attention None 406 * @param id [IN] type #hi_spi_idx，SPI ID.CNcomment:ID 号。CNend 407 * @param lb_en [IN] type #hi_bool，loop back enable.CNcomment:使能回环模式。CNend 408 * 409 * @retval #0 Success 410 * @retval #Other Failure. For details, see hi_errno.h. 411 * @par 依赖: 412 * @li hi_spi.h：Describes the SPI APIs.CNcomment:文件用于描述SPI相关接口。CNend 413 * @see None 414 */ 415 hi_u32 hi_spi_set_loop_back_mode(hi_spi_idx id, hi_bool lb_en); 416 417 418 #endif 419