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 i2c \n 16 * 17 * History: \n 18 * 2022-06-07, Create file. \n 19 */ 20 #ifndef HAL_I2C_H 21 #define HAL_I2C_H 22 23 #include <stdint.h> 24 #include "errcode.h" 25 #include "i2c_porting.h" 26 27 #ifdef __cplusplus 28 #if __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 #endif /* __cplusplus */ 32 33 /** 34 * @defgroup drivers_hal_i2c_api I2C 35 * @ingroup drivers_hal_i2c 36 * @{ 37 */ 38 39 #define I2C_SS_MODE_BAUDRATE_HIGH_LIMIT (100 * 1000) /*!< @if Eng I2C baudrate high limit in standard mode. 40 @else 标准模式下I2C波特率最大限值 @endif */ 41 #define I2C_FS_MODE_BAUDRATE_HIGH_LIMIT (400 * 1000) /*!< @if Eng I2C baudrate high limit in fast mode. 42 @else 快速模式下I2C波特率最大限值 @endif */ 43 #define I2C_HS_MODE_BAUDRATE_HIGH_LIMIT (3400 * 1000) /*!< @if Eng I2C baudrate high limit in high speed mode. 44 @else 高速模式下I2C波特率最大限值 @endif */ 45 46 #define I2C_HS_MODE_MASTER_CODE_MAX 7 /*!< @if Eng I2C max master code in high speed mode. 47 @else 高速模式下I2C主机码最大值 @endif */ 48 49 /** 50 * @if Eng 51 * @brief Definition of I2C speed mode. 52 * @else 53 * @brief I2C速率模式定义 54 * @endif 55 */ 56 typedef enum hal_i2c_speed_mode { 57 I2C_SPEED_MODE_HARDCODE = 0, 58 I2C_SPEED_MODE_SS = 0, /*!< @if Eng I2C standard speed mode. 59 @else I2C标速模式。 @endif */ 60 I2C_SPEED_MODE_FS, /*!< @if Eng I2C fast speed mode. 61 @else I2C快速模式。 @endif */ 62 I2C_SPEED_MODE_HS, /*!< @if Eng I2C high speed mode. 63 @else I2C高速模式。 @endif */ 64 I2C_SPEED_MODE_MAX_NUM 65 } hal_i2c_speed_mode_t; 66 67 /** 68 * @if Eng 69 * @brief Definition of I2C data operation type. 70 * @else 71 * @brief I2C数据操作类型定义。 72 * @endif 73 */ 74 typedef enum hal_i2c_data_operation_type { 75 I2C_DATA_OPERATION_TYPE_POLL, /*!< @if Eng I2C data operation type is poll. 76 @else I2C 对数据进行轮询处理 @endif */ 77 I2C_DATA_OPERATION_TYPE_INT, /*!< @if Eng I2C data operation type is interrupt. 78 @else I2C 对数据进行中断处理 @endif */ 79 I2C_DATA_OPERATION_TYPE_DMA, /*!< @if Eng I2C data operation type is dma. 80 @else I2C 对数据进行DMA处理 @endif */ 81 I2C_DATA_OPERATION_TYPE_INVLAID 82 } hal_i2c_data_operation_type_t; 83 84 /** 85 * @if Eng 86 * @brief Definition of the event ID of hal i2c. 87 * @else 88 * @brief I2C事件ID的定义。 89 * @endif 90 */ 91 typedef enum hal_i2c_evt_id { 92 I2C_EVT_TX_READY = 0, /*!< @if Eng Tx fifo is at or below tx threshold, TX_EMPTY interrupt. 93 @else 发送FIFO等于小于发送阈值，TX_EMPTY中断。 @endif */ 94 I2C_EVT_RX_READY, /*!< @if Eng Rx fifo reaches or goes above the rx threshold, RX_FULL interrupt. 95 @else 接收FIFO到达或者超过接收阈值，RX_FULL中断。 @endif */ 96 I2C_EVT_TX_AVAILABLE, /*!< @if Eng I2C acts as a slave and receives master read command, RD_REQ interrupt. 97 @else I2C作为从机收到主机读取数据指令，RD_REQ中断。 @endif */ 98 I2C_EVT_TRANSMITION_START, /*!< @if Eng New Send or receive process start,START_DET interrupt. 99 @else 新的传输或者接收任务开始，START_DET中断。 @endif */ 100 I2C_EVT_TRANSMITION_DONE, /*!< @if Eng Send or receive process end, STOP_DET interrupt. 101 @else 传输或者接收任务结束，STOP_DET中断。 @endif */ 102 I2C_EVT_TRANSMITION_ABRT, /*!< @if Eng Send or receive process abrt, TX_ABRT interrupt. 103 @else 传输或者接收出现异常，TX_ABRT中断。 @endif */ 104 I2C_EVT_TRANSMITION_BUSY, /*!< @if Eng Bus busy, BUS_BUSY interrupt. 105 @else 总线忙，BUS_BUSY中断。 @endif */ 106 I2C_EVT_INVALID = 0xF 107 } hal_i2c_evt_id_t; 108 109 /** 110 * @if Eng 111 * @brief Definition of the contorl ID of hal i2c. 112 * @else 113 * @brief I2C控制ID定义。 114 * @endif 115 */ 116 typedef enum hal_i2c_ctrl_id { 117 I2C_CTRL_WRITE_PREPARE = 0, /*!< @if Eng Prepare configuration before write. 118 @else 发送前的准备配置。 @endif */ 119 I2C_CTRL_WRITE_RESTORE, /*!< @if Eng Restore configuration after write. 120 @else 发送完成后恢复配置。 @endif */ 121 I2C_CTRL_READ_PREPARE, /*!< @if Eng Prepare configuration before read. 122 @else 接收数据前准备配置。 @endif */ 123 I2C_CTRL_READ_RESTORE, /*!< @if Eng Restore configuration after read. 124 @else 发送完成后恢复配置。 @endif */ 125 I2C_CTRL_GET_WRITE_NUM, /*!< @if Eng Get write num can be used. 126 @else 获取可以发送的数据长度。 @endif */ 127 I2C_CTRL_GET_READ_NUM, /*!< @if Eng Get read fifo num can be used. 128 @else 获取可以发送的数据长度。 @endif */ 129 I2C_CTRL_CHECK_TX_AVAILABLE, /*!< @if Eng Check whether tx fifo can be filled 130 @else 检查是否可以对tx fifo 进行填充。 @endif */ 131 I2C_CTRL_CHECK_RX_AVAILABLE, /*!< @if Eng Check whether rx fifo is accessible 132 @else 检查是否可以对rx fifo 进行访问。 @endif */ 133 I2C_CTRL_FLUSH_RX_FIFO, /*!< @if Eng Flush rx fifo. 134 @else 刷新RX FIFO。 @endif */ 135 I2C_CTRL_CHECK_TX_PROCESS_DONE, /*!< @if Eng Ensure send process done. 136 @else 确认发送传输过程是否完成。 @endif */ 137 I2C_CTRL_CHECK_RX_PROCESS_DONE, /*!< @if Eng Ensure receive process done. 138 @else 确认接收传输过程是否完成。 @endif */ 139 I2C_CTRL_CHECK_RESTART_READY, /*!< @if Eng Ensure can start cfg restart. 140 @else 确认可以开始配置restart。 @endif */ 141 I2C_CTRL_NORMAL_MAX = I2C_CTRL_CHECK_RESTART_READY, 142 I2C_CTRL_CHECK_TRANSMIT_ABRT, /*!< @if Eng Check transmit abnormal abort status. 143 @else 检查传输异常取消状态。 @endif */ 144 I2C_CTRL_GET_DMA_DATA_ADDR, /*!< @if get data cmd register. 145 @else 获取数据命令寄存器。 @endif */ 146 I2C_CTRL_CHECK_TX_FIFO_EMPTY, /*!< @if get Check whether tx fifo is empth. 147 @else 检查tx fifo 是否为空。 @endif */ 148 I2C_CTRL_MAX, 149 I2C_CTRL_ID_INVALID = 0x1F 150 } hal_i2c_ctrl_id_t; 151 152 /** 153 * @if Eng 154 * @brief Definition of I2C prepare params for send or receive. 155 * @else 156 * @brief I2C准备收发的参数数据结构定义。 157 * @endif 158 */ 159 typedef struct hal_i2c_prepare_config { 160 uint8_t operation_type; /*!< @if Eng Operation type of send or receive. 161 @else 收发的操作类型。 @endif */ 162 uint8_t reserved; 163 uint16_t addr; /*!< @if Eng I2C Address for send or receive, valid only for master 164 @else 主机I2C要对接收发的从机地址。 @endif */ 165 uint32_t total_len; /*!< @if Eng total_len len for send or receive, valid only for master 166 @else 主机I2C要收发的数据长度。 @endif */ 167 } hal_i2c_prepare_config_t; 168 169 /** 170 * @if Eng 171 * @brief Definition of I2C data buffer wrap. 172 * @else 173 * @brief I2C缓存数据封装数据结构定义。 174 * @endif 175 */ 176 typedef struct hal_i2c_buffer_wrap { 177 uint8_t *buffer; /*!< @if Eng Buffer pointer. 178 @else 缓存数据的buffer指针。 @endif */ 179 uint32_t len; /*!< @if Eng Buffer size in bytes. 180 @else 缓存数据Buffer的长度。 @endif */ 181 uint8_t stop_flag; /*!< @if Eng Stop flag，stop issused after send or receive. 182 @else 缓存数据发送或者接收完成后是否要停止命令。 @endif */ 183 uint8_t restart_flag; /*!< @if Eng Restart flag，restart issused before send or receive. 184 @else 缓存数据发送或者接收是否要发重新开始命令。 @endif */ 185 uint8_t reserved[2]; 186 } hal_i2c_buffer_wrap_t; 187 188 /** 189 * @if Eng 190 * @brief Callback of I2C. 191 * @param [in] bus The I2C bus. see @ref i2c_bus_t 192 * @param [in] evt Event ID. see @ref hal_i2c_evt_id_t 193 * @param [in] param Parameter pointer of callback. 194 * @retval ERRCODE_SUCC Success. 195 * @retval Other Failure. For details, see @ref errcode_t 196 * @else 197 * @brief I2C的回调函数 198 * @param [in] bus I2C索引。参考 @ref i2c_bus_t 199 * @param [in] evt 事件ID。参考 @ref hal_i2c_evt_id_t 200 * @param [in] param 传递给回调的参数指针。 201 * @retval ERRCODE_SUCC 成功。 202 * @retval Other 失败。参考 @ref errcode_t 203 * @endif 204 */ 205 typedef errcode_t (*hal_i2c_callback_t)(i2c_bus_t bus, hal_i2c_evt_id_t evt, uintptr_t param); 206 207 /** 208 * @if Eng 209 * @brief Init device as master for hal I2C. 210 * @param [in] bus The I2C bus. see @ref i2c_bus_t 211 * @param [in] baudrate Baudrate of the i2c controller. 212 * @param [in] hscode High speed mode master code of the i2c controller, need be unique. 213 * @param [in] callback Callback of the i2c controller. see @ref hal_i2c_callback_t 214 * @retval ERRCODE_SUCC Success. 215 * @retval Other Failure. For details, see @ref errcode_t 216 * @else 217 * @brief HAL层I2C初始化为主机。 218 * @param [in] bus I2C索引。参考 @ref i2c_bus_t 219 * @param [in] baudrate I2C控制器的波特率。 220 * @param [in] hscode I2C控制器的主机码，用于高速仲裁，需要唯一。 221 * @param [in] callback I2C控制器的中断回调。参考 @ref hal_i2c_callback_t 222 * @retval ERRCODE_SUCC 成功。 223 * @retval Other 失败。参考 @ref errcode_t 224 * @endif 225 */ 226 errcode_t hal_i2c_master_init(i2c_bus_t bus, uint32_t baudrate, 227 uint8_t hscode, hal_i2c_callback_t callback); 228 229 /** 230 * @if Eng 231 * @brief Init device as slave for hal I2C. 232 * @param [in] bus The I2C bus. see @ref i2c_bus_t 233 * @param [in] baudrate Baudrate of the i2c controller. 234 * @param [in] addr I2C slave address of the i2c controller. 235 * @param [in] callback Callback of the i2c controller. see @ref hal_i2c_callback_t 236 * @retval ERRCODE_SUCC Success. 237 * @retval Other Failure. For details, see @ref errcode_t 238 * @else 239 * @brief HAL层I2C初始化为主机。 240 * @param [in] bus I2C索引。参考 @ref i2c_bus_t 241 * @param [in] baudrate I2C控制器的波特率。 242 * @param [in] addr I2C控制器的从机地址。 243 * @param [in] callback I2C控制器的中断回调。参考 @ref hal_i2c_callback_t 244 * @retval ERRCODE_SUCC 成功。 245 * @retval Other 失败。参考 @ref errcode_t 246 * @endif 247 */ 248 errcode_t hal_i2c_slave_init(i2c_bus_t bus, uint32_t baudrate, 249 uint16_t addr, hal_i2c_callback_t callback); 250 251 /** 252 * @if Eng 253 * @brief Deinit device for hal I2C. 254 * @param [in] bus The i2c bus. see @ref i2c_bus_t 255 * @retval ERRCODE_SUCC Success. 256 * @retval Other Failure. For details, see @ref errcode_t 257 * @else 258 * @brief HAL层I2C去初始化接口 259 * @param [in] bus I2C索引。参考 @ref i2c_bus_t 260 * @retval ERRCODE_SUCC 成功。 261 * @retval Other 失败。参考 @ref errcode_t 262 * @endif 263 */ 264 errcode_t hal_i2c_deinit(i2c_bus_t bus); 265 266 /** 267 * @if Eng 268 * @brief Control interface for hal I2C. 269 * @param [in] bus The I2C bus. see @ref i2c_bus_t 270 * @param [in] id Control ID of the I2C controller. see @ref hal_i2c_ctrl_id_t 271 * @param [in] param Parameter for callback. 272 * @retval ERRCODE_SUCC Success. 273 * @retval Other Failure. For details, see @ref errcode_t 274 * @else 275 * @brief HAL层I2C控制接口。 276 * @param [in] bus I2C索引。参考 @ref i2c_bus_t 277 * @param [in] id I2C控制请求ID。参考 @ref hal_i2c_ctrl_id_t 278 * @param [in] param 传递给控制回调的参数。 279 * @retval ERRCODE_SUCC 成功。 280 * @retval Other 失败。参考 @ref errcode_t 281 * @endif 282 */ 283 errcode_t hal_i2c_ctrl(i2c_bus_t bus, hal_i2c_ctrl_id_t id, uintptr_t param); 284 285 /** 286 * @if Eng 287 * @brief Write interface for hal I2C. 288 * @param [in] bus The I2C bus. see @ref i2c_bus_t 289 * @param [in] data Send data buffer and send configuration parameters. see @ref hal_i2c_buffer_wrap_t 290 * @retval ERRCODE_SUCC Success. 291 * @retval Other Failure. For details, see @ref errcode_t 292 * @else 293 * @brief HAL层I2C发送数据接口。 294 * @param [in] bus I2C索引。参考 @ref i2c_bus_t 295 * @param [in] data 发送数据的缓冲地址及发送配置参数。参考 @ref hal_i2c_buffer_wrap_t 296 * @retval ERRCODE_SUCC 成功。 297 * @retval Other 失败。参考 @ref errcode_t 298 * @endif 299 */ 300 errcode_t hal_i2c_write(i2c_bus_t bus, hal_i2c_buffer_wrap_t *data); 301 302 /** 303 * @if Eng 304 * @brief Read interface for hal I2C. 305 * @param [in] bus The device pointer to manager the hal I2C. 306 * @param [in] data Read data buffer and read configuration parameters. see @ref hal_i2c_buffer_wrap_t 307 * @retval ERRCODE_SUCC Success. 308 * @retval Other Failure. For details, see @ref errcode_t 309 * @else 310 * @brief HAL层I2C读取数据接口。 311 * @param [in] bus I2C索引。参考 @ref i2c_bus_t 312 * @param [in] data 读取数据的缓冲地址及读取配置参数。参考 @ref hal_i2c_buffer_wrap_t 313 * @retval ERRCODE_SUCC 成功。 314 * @retval Other 失败。参考 @ref errcode_t 315 * @endif 316 */ 317 errcode_t hal_i2c_read(i2c_bus_t bus, hal_i2c_buffer_wrap_t *data); 318 319 /** 320 * @} 321 */ 322 323 #ifdef __cplusplus 324 #if __cplusplus 325 } 326 #endif /* __cplusplus */ 327 #endif /* __cplusplus */ 328 329 #endif 330