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*/
45typedef 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*/
55typedef 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*/
65typedef 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*/
75typedef 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*/
87typedef 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.
107CNcomment:通信参数：每帧的传输大小端。CNend
108*/
109typedef 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*/
131typedef hi_void (*hi_spi_usr_func)(hi_void);
132
133/**
134 * @ingroup iot_spi
135 *
136 * Data communication parameter.CNcomment:数据通信参数。CNend
137 */
138typedef 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 */
159typedef 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).
175CNcomment:发送数据长度（单位：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*/
184hi_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).
198CNcomment:接收数据长度（单位：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*/
207hi_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).
221CNcomment:发送数据长度（单位：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*/
229hi_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).
243CNcomment:接收数据长度（单位：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*/
251hi_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).
266CNcomment:接收数据长度（单位：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*/
274hi_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*/
295hi_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*/
320hi_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 */
338hi_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*/
357hi_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*/
376hi_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*/
396hi_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*/
415hi_u32 hi_spi_set_loop_back_mode(hi_spi_idx id, hi_bool lb_en);
416
417
418#endif
419