1/**
2 * @file hi_i2c.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
18/** @defgroup iot_i2c  I2C
19 *  @ingroup drivers
20 */
21#ifndef __HI_I2C_H__
22#define __HI_I2C_H__
23
24#include <hi_types_base.h>
25
26/*
27 * I2C Interface
28 */
29#define I2C_RATE_DEFAULT  100000
30
31typedef hi_void (*i2c_reset_func)(hi_void);
32typedef hi_void (*i2c_prepare_func)(hi_void);
33typedef hi_void (*i2c_restore_func)(hi_void);
34
35/**
36 * @ingroup iot_i2c
37 *
38 * I2C callback function. CNcomment:I2C回调函数。CNend
39 */
40typedef struct {
41    i2c_reset_func   reset_func;    /**< This function is called back when the communication with the slave device
42                                         is abnormal.CNcomment:I2C从异常处理函数CNend */
43    i2c_prepare_func prepare_func;  /**< This function is called back before the I2C read/write operation to implement
44                                         the preparations before the I2C operation.
45                                         CNcomment:I2C操作前准备函数CNend */
46    i2c_restore_func restore_func;  /**< After the I2C read/write operation is performed, this function is
47                                         called back to implement the recovery after the I2C operation.
48                                         CNcomment:I2C操作后恢复函数CNend */
49} hi_i2c_func;
50
51/**
52 * @ingroup iot_i2c
53 *
54 * I2C TX/RX data descriptor. CNcomment:I2C发送/接收数据描述符。CNend
55 */
56typedef struct {
57    hi_u8*  send_buf;        /**< Data TX pointer. The user needs to ensure that no null pointer is transferred.
58                                CNcomment:数据发送指针CNend */
59    hi_u32  send_len;        /**< Length of sent data (unit: byte).
60                                CNcomment:发送数据长度（单位：byte）CNend */
61    hi_u8*  receive_buf;     /**< Data RX pointer. CNcomment:数据接收指针CNend */
62    hi_u32  receive_len;     /**< Length of received data (unit: byte).
63                                CNcomment:接收数据长度（单位：byte）CNend */
64} hi_i2c_data;
65
66/**
67 * @ingroup iot_i2c
68 *
69 * I2C hardware index. CNComment:I2C硬件设备枚举。CNend
70 */
71typedef enum {
72    HI_I2C_IDX_0,
73    HI_I2C_IDX_1,
74} hi_i2c_idx;
75
76/**
77* @ingroup  iot_i2c
78* @brief  Set I2C baudrate. CNcomment:I2C设置波特率。CNend
79*
80* @par 描述:
81*           Set I2C baudrate. CNcomment:I2C设置波特率。CNend
82*
83* @attention Multiple tasks are not protected (multiple tasks are not supported). CNcomment:未作
84多任务保护（不支持多任务）。CNend
85* @param  id       [IN] type #hi_i2c_idx，I2C hardware selection. CNcomment:I2C硬件设备选择。CNend
86* @param  baudrate [IN] type #hi_u32，I2C baudrate. CNcomment:I2C波特率。CNend
87*
88* @retval #0          Success.
89* @retval #Other      Failure. For details, see hi_errno.h.
90* @par 依赖:
91*           @li hi_i2c.h：Declares the API.CNcomment:该接口声明所在的头文件。CNend
92* @see  hi_i2c_write|hi_i2c_receive。
93*/
94hi_u32 hi_i2c_set_baudrate(hi_i2c_idx id, hi_u32 baudrate);
95
96/**
97* @ingroup  iot_i2c
98* @brief  I2C data TX and RX.CNcomment:I2C发送与接收数据。CNend
99*
100* @par 描述:
101*           The I2C sends data to the slave device and then receives data from the slave device.
102CNcomment:I2C向从机发送数据，然后接收从机数据。CNend
103*
104* @attention Multi-tasking is not supported. CNcomment:未作多任务保护（不支持多任务）。CNend
105* @param  id       [IN] type #hi_i2c_idx，I2C hardware selection. CNcomment:I2C硬件设备选择。CNend
106* @param  device_addr [IN] type #hi_u16，The device ID. High three bits of offset address of the I2C device on chipset.
107CNcomment:设备号及设备片内偏移地址高3位（从设备哪个地方开始读）。CNend
108* @param  i2c_data  [IN/OUT] type #const hi_i2c_data*，The data descriptor to be received.
109*                             The structure member data sending pointer and data receiving pointer cannot be null.
110CNcomment:待接收数据描述符，结构体成员数据发送指针和数据接收指针都不为空。CNend
111*
112* @retval #0          Success.
113* @retval #Other      Failure. For details, see hi_errno.h.
114* @par 依赖:
115*           @li hi_i2c.h：Declares the API.CNcomment:该接口声明所在的头文件。CNend
116* @see  hi_i2c_write|hi_i2c_receive。
117*/
118hi_u32 hi_i2c_writeread(hi_i2c_idx id, hi_u16 device_addr, const hi_i2c_data *i2c_data);
119
120/**
121* @ingroup  iot_i2c
122* @brief  I2C data TX. CNcomment:I2C发送数据。CNend
123*
124* @par 描述:
125*           I2C data TX. CNcomment:I2C发送数据。CNend
126*
127* @attention Multiple tasks are not protected (multiple tasks are not supported). CNcomment:未作
128多任务保护（不支持多任务）。CNend
129* @param  id       [IN] type #hi_i2c_idx，I2C hardware selection. CNcomment:I2C硬件设备选择。CNend
130* @param  device_addr [IN] type #hi_u16，The device ID. High three bits of offset address of the I2C device on chipset.
131CNcomment:设备号及设备片内偏移地址高3位（从设备哪个地方开始读）。CNend
132* @param  i2c_data  [IN] type #const hi_i2c_data*，The data descriptor to be received. The structure member data sending
133*                             pointer and data receiving pointer cannot be null.
134CNcomment:待接收数据描述符，结构体成员数据发送指针和数据接收指针都不为空。CNend
135*
136* @retval #0          Success.
137* @retval #Other      Failure. For details, see hi_errno.h.
138* @par 依赖:
139*           @li hi_i2c.h：Declares the API.CNcomment:该接口声明所在的头文件。CNend
140* @see  hi_i2c_writeread|hi_i2c_receive。
141*/
142hi_u32 hi_i2c_write(hi_i2c_idx id, hi_u16 device_addr, const hi_i2c_data *i2c_data);
143
144/**
145* @ingroup  iot_i2c
146* @brief  I2C data RX. CNcomment:I2C接收数据。CNend
147*
148* @par 描述:
149*            I2C data RX. CNcomment:I2C接收数据。CNend
150*
151* @attention Multi-tasking is not supported. CNcomment:未作多任务保护（不支持多任务）。CNend
152* @param  id       [IN] type #hi_i2c_idx，I2C hardware selection. CNcomment:I2C硬件设备选择。CNend
153* @param  device_addr [IN] type #hi_u16，The device ID. High three bits of offset address of the I2C device on chipset.
154CNcomment:设备号及设备片内偏移地址高3位（从设备哪个地方开始读）。CNend
155* @param  i2c_data  [OUT] type #const hi_i2c_data*，The data descriptor to be received. The structure member data sending
156*                             pointer and data receiving pointer cannot be null.
157CNcomment:待接收数据描述符，结构体成员数据发送指针和数据接收指针都不为空。CNend
158*
159* @retval #0          Success.
160* @retval #Other      Failure. For details, see hi_errno.h.
161* @par 依赖:
162*           @li hi_i2c.h：Declares the API.CNcomment:该接口声明所在的头文件。CNend
163* @see  hi_i2c_write|hi_i2c_sendreceive。
164*/
165hi_u32 hi_i2c_read(hi_i2c_idx id, hi_u16 device_addr, const hi_i2c_data *i2c_data);
166
167/**
168* @ingroup  iot_i2c
169* @brief  Initializes the I2C controller. CNcomment:I2C初始化。CNend
170*
171* @par 描述:
172*           Initializes the I2C controller. CNcomment:I2C初始化。CNend
173*
174* @attention None
175* @param  id       [IN] type #hi_i2c_idx，I2C hardware selection. CNcomment:I2C硬件设备选择。CNend
176* @param  baudrate [IN] type #hi_u32，I2C baudrate. CNcomment:I2C波特率。CNend
177*
178* @retval #0          Success.
179* @retval #Other      Failure. For details, see hi_errno.h.
180* @par 依赖:
181*           @li hi_i2c.h：Declares the API.CNcomment:该接口声明所在的头文件。CNend
182* @see  hi_i2c_deinit。
183*/
184hi_u32 hi_i2c_init(hi_i2c_idx id, hi_u32 baudrate);
185
186/**
187* @ingroup  iot_i2c
188* @brief  Exits the I2C module.CNcomment:退出I2C模块。CNend
189*
190* @par 描述:
191*          Exits the I2C module. CNcomment:退出I2C模块。CNend
192*
193* @attention This API is called after hi_i2c_init is called. CNcomment:hi_i2c_init调用后再使用。CNend
194* @param  id       [IN] type #hi_i2c_idx，I2C hardware selection. CNcomment:I2C硬件设备选择。CNend
195*
196* @retval #0          Success.
197* @retval #Other      Failure. For details, see hi_errno.h.
198* @par 依赖:
199*           @li hi_i2c.h：Declares the API.CNcomment:该接口声明所在的头文件。CNend
200* @see  hi_i2c_init。
201*/
202hi_u32 hi_i2c_deinit(hi_i2c_idx id);
203
204/**
205* @ingroup  iot_i2c
206* @brief  Registers the I2C callback function.CNcomment:注册I2C回调函数。CNend
207*
208* @par 描述:
209*           Registers the I2C callback function, for extension.CNcomment:注册I2C回调函数，用于扩展。CNend
210*
211* @attention None
212* @param  id      [IN] type #hi_i2c_idx，I2C hardware selection. CNcomment:I2C硬件设备选择。CNend
213* @param  pfn     [IN] type #hi_i2c_func，Callback function. CNcomment:回调函数。CNend
214*
215* @retval #0          Success.
216* @retval #Other      Failure. For details, see hi_errno.h.
217* @par 依赖:
218*           @li hi_i2c.h：Declares the API.CNcomment:该接口声明所在的头文件。CNend
219* @see  None
220*/
221hi_void hi_i2c_register_reset_bus_func(hi_i2c_idx id, hi_i2c_func pfn);
222
223#endif
224