1 // Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD 2 // 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 /******************************************************************************* 16 * NOTICE 17 * The hal is not public api, don't use in application code. 18 * See readme.md in hal/include/hal/readme.md 19 ******************************************************************************/ 20 21 // The HAL layer for I2C 22 23 #pragma once 24 #include "hal/i2c_ll.h" 25 #include "hal/i2c_types.h" 26 27 /** 28 * @brief I2C hal Context definition 29 */ 30 typedef struct { 31 i2c_dev_t *dev; 32 uint32_t version; 33 } i2c_hal_context_t; 34 35 /** 36 * @brief Write the I2C rxfifo with the given length 37 * 38 * @param hal Context of the HAL layer 39 * @param wr_data Pointer to data buffer 40 * @param wr_size Amount of data needs write 41 * 42 * @return None 43 */ 44 #define i2c_hal_write_txfifo(hal,wr_data,wr_size) i2c_ll_write_txfifo((hal)->dev,wr_data,wr_size) 45 46 /** 47 * @brief Read the I2C rxfifo with the given length 48 * 49 * @param hal Context of the HAL layer 50 * @param buf Pointer to data buffer 51 * @param rd_size Amount of data needs read 52 * 53 * @return None 54 */ 55 #define i2c_hal_read_rxfifo(hal,buf,rd_size) i2c_ll_read_rxfifo((hal)->dev,buf,rd_size) 56 57 /** 58 * @brief Write I2C cmd register 59 * 60 * @param hal Context of the HAL layer 61 * @param cmd I2C hardware command 62 * @param cmd_idx The index of the command register, should be less than 16 63 * 64 * @return None 65 */ 66 #define i2c_hal_write_cmd_reg(hal,cmd, cmd_idx) i2c_ll_write_cmd_reg((hal)->dev,cmd,cmd_idx) 67 68 /** 69 * @brief Configure the I2C to triger a trasaction 70 * 71 * @param hal Context of the HAL layer 72 * 73 * @return None 74 */ 75 #define i2c_hal_trans_start(hal) i2c_ll_trans_start((hal)->dev) 76 77 /** 78 * @brief Enable I2C master RX interrupt 79 * 80 * @param hal Context of the HAL layer 81 * 82 * @return None 83 */ 84 #define i2c_hal_enable_master_rx_it(hal) i2c_ll_master_enable_rx_it((hal)->dev) 85 86 /** 87 * @brief Enable I2C master TX interrupt 88 * 89 * @param hal Context of the HAL layer 90 * 91 * @return None 92 */ 93 #define i2c_hal_enable_master_tx_it(hal) i2c_ll_master_enable_tx_it((hal)->dev) 94 95 /** 96 * @brief Clear I2C slave TX interrupt 97 * 98 * @param hal Context of the HAL layer 99 * 100 * @return None 101 */ 102 #define i2c_hal_slave_clr_tx_it(hal) i2c_ll_slave_clr_tx_it((hal)->dev) 103 104 /** 105 * @brief Clear I2C slave RX interrupt 106 * 107 * @param hal Context of the HAL layer 108 * 109 * @return None 110 */ 111 #define i2c_hal_slave_clr_rx_it(hal) i2c_ll_slave_clr_rx_it((hal)->dev) 112 113 /** 114 * @brief Init the I2C master. 115 * 116 * @param hal Context of the HAL layer 117 * @param i2c_num I2C port number 118 * 119 * @return None 120 */ 121 void i2c_hal_master_init(i2c_hal_context_t *hal, i2c_port_t i2c_num); 122 123 /** 124 * @brief Init the I2C slave. 125 * 126 * @param hal Context of the HAL layer 127 * @param i2c_num I2C port number 128 * 129 * @return None 130 */ 131 void i2c_hal_slave_init(i2c_hal_context_t *hal, i2c_port_t i2c_num); 132 133 /** 134 * @brief Reset the I2C hw txfifo 135 * 136 * @param hal Context of the HAL layer 137 * 138 * @return None 139 */ 140 void i2c_hal_txfifo_rst(i2c_hal_context_t *hal); 141 142 /** 143 * @brief Reset the I2C hw rxfifo 144 * 145 * @param hal Context of the HAL layer 146 * 147 * @return None 148 */ 149 void i2c_hal_rxfifo_rst(i2c_hal_context_t *hal); 150 151 /** 152 * @brief Configure the I2C data MSB bit shifted first or LSB bit shifted first. 153 * 154 * @param hal Context of the HAL layer 155 * @param tx_mode Data format of TX 156 * @param rx_mode Data format of RX 157 * 158 * @return None 159 */ 160 void i2c_hal_set_data_mode(i2c_hal_context_t *hal, i2c_trans_mode_t tx_mode, i2c_trans_mode_t rx_mode); 161 162 /** 163 * @brief Configure the I2C hardware filter function. 164 * 165 * @param hal Context of the HAL layer 166 * @param filter_num If the glitch period on the line is less than this value(in APB cycle), it will be filtered out 167 * If `filter_num == 0`, the filter will be disabled 168 * 169 * @return None 170 */ 171 void i2c_hal_set_filter(i2c_hal_context_t *hal, uint8_t filter_num); 172 173 /** 174 * @brief Get the I2C hardware filter configuration 175 * 176 * @param hal Context of the HAL layer 177 * @param filter_num Pointer to accept the hardware filter configuration 178 * 179 * @return None 180 */ 181 void i2c_hal_get_filter(i2c_hal_context_t *hal, uint8_t *filter_num); 182 183 /** 184 * @brief Configure the I2C SCL timing 185 * 186 * @param hal Context of the HAL layer 187 * @param hight_period SCL high period 188 * @param low_period SCL low period 189 * 190 * @return None 191 */ 192 void i2c_hal_set_scl_timing(i2c_hal_context_t *hal, int hight_period, int low_period); 193 194 /** 195 * @brief Configure the I2C master SCL frequency 196 * 197 * @param hal Context of the HAL layer 198 * @param src_clk The I2C Source clock frequency 199 * @param scl_freq The SCL frequency to be set 200 * 201 * @return None 202 */ 203 void i2c_hal_set_scl_freq(i2c_hal_context_t *hal, uint32_t src_clk, uint32_t scl_freq); 204 205 /** 206 * @brief Clear the I2C interrupt status with the given mask 207 * 208 * @param hal Context of the HAL layer 209 * @param mask The interrupt bitmap needs to be clearned 210 * 211 * @return None 212 */ 213 void i2c_hal_clr_intsts_mask(i2c_hal_context_t *hal, uint32_t mask); 214 215 /** 216 * @brief Enable the I2C interrupt with the given mask 217 * 218 * @param hal Context of the HAL layer 219 * @param mask The interrupt bitmap needs to be enabled 220 * 221 * @return None 222 */ 223 void i2c_hal_enable_intr_mask(i2c_hal_context_t *hal, uint32_t mask); 224 225 /** 226 * @brief Disable the I2C interrupt with the given mask 227 * 228 * @param hal Context of the HAL layer 229 * @param mask The interrupt bitmap needs to be disabled 230 * 231 * @return None 232 */ 233 void i2c_hal_disable_intr_mask(i2c_hal_context_t *hal, uint32_t mask); 234 235 /** 236 * @brief Configure the I2C memory access mode, FIFO mode or none FIFO mode 237 * 238 * @param hal Context of the HAL layer 239 * @param fifo_mode_en Set true to enable FIFO access mode, else set it false 240 * 241 * @return None 242 */ 243 void i2c_hal_set_fifo_mode(i2c_hal_context_t *hal, bool fifo_mode_en); 244 245 /** 246 * @brief Configure the I2C timeout value 247 * 248 * @param hal Context of the HAL layer 249 * @param tout_val the timeout value to be set 250 * 251 * @return None 252 */ 253 void i2c_hal_set_tout(i2c_hal_context_t *hal, int tout_val); 254 255 /** 256 * @brief Get the I2C time out configuration 257 * 258 * @param tout_val Pointer to accept the timeout configuration 259 * 260 * @return None 261 */ 262 void i2c_hal_get_tout(i2c_hal_context_t *hal, int *tout_val); 263 264 /** 265 * @brief Configure the I2C slave address 266 * 267 * @param hal Context of the HAL layer 268 * @param slave_addr Slave address 269 * @param addr_10bit_en Set true to enable 10-bit slave address mode, Set false to enable 7-bit address mode 270 * 271 * @return None 272 */ 273 void i2c_hal_set_slave_addr(i2c_hal_context_t *hal, uint16_t slave_addr, bool addr_10bit_en); 274 275 /** 276 * @brief Configure the I2C stop timing 277 * 278 * @param hal Context of the HAL layer 279 * @param stop_setup The stop condition setup period (in APB cycle) 280 * @param stop_hold The stop condition hold period (in APB cycle) 281 * 282 * @return None 283 */ 284 void i2c_hal_set_stop_timing(i2c_hal_context_t *hal, int stop_setup, int stop_hold); 285 286 /** 287 * @brief Configure the I2C start timing 288 * 289 * @param hal Context of the HAL layer 290 * @param start_setup The start condition setup period (in APB cycle) 291 * @param start_hold The start condition hold period (in APB cycle) 292 * 293 * @return None 294 */ 295 void i2c_hal_set_start_timing(i2c_hal_context_t *hal, int start_setup, int start_hold); 296 297 /** 298 * @brief Configure the I2C sda sample timing 299 * 300 * @param hal Context of the HAL layer 301 * @param sda_sample The SDA sample time (in APB cycle) 302 * @param sda_hold The SDA hold time (in APB cycle) 303 * 304 * @return None 305 */ 306 void i2c_hal_set_sda_timing(i2c_hal_context_t *hal, int sda_sample, int sda_hold); 307 308 /** 309 * @brief Configure the I2C txfifo empty threshold value 310 * 311 * @param hal Context of the HAL layer. 312 * @param empty_thr TxFIFO empty threshold value 313 * 314 * @return None 315 */ 316 void i2c_hal_set_txfifo_empty_thr(i2c_hal_context_t *hal, uint8_t empty_thr); 317 318 /** 319 * @brief Configure the I2C rxfifo full threshold value 320 * 321 * @param hal Context of the HAL layer 322 * @param full_thr RxFIFO full threshold value 323 * 324 * @return None 325 */ 326 void i2c_hal_set_rxfifo_full_thr(i2c_hal_context_t *hal, uint8_t full_thr); 327 328 /** 329 * @brief Get the I2C interrupt status 330 * 331 * @param hal Context of the HAL layer 332 * @param mask Pointer to accept the interrupt status 333 * 334 * @return None 335 */ 336 void i2c_hal_get_intsts_mask(i2c_hal_context_t *hal, uint32_t *mask); 337 338 /** 339 * @brief Check if the I2C bus is busy 340 * 341 * @param hal Context of the HAL layer 342 * 343 * @return True if the bus is busy, otherwise, fale will be returned 344 */ 345 bool i2c_hal_is_bus_busy(i2c_hal_context_t *hal); 346 347 /** 348 * @brief Get the I2C sda sample timing configuration 349 * 350 * @param hal Context of the HAL layer 351 * @param sample_time Pointer to accept the SDA sample time 352 * @param hold_time Pointer to accept the SDA hold time 353 * 354 * @return None 355 */ 356 void i2c_hal_get_sda_timing(i2c_hal_context_t *hal, int *sample_time, int *hold_time); 357 358 /** 359 * @brief Get the I2C stop timing configuration 360 * 361 * @param hal Context of the HAL layer 362 * @param setup_time Pointer to accept the stop condition setup period 363 * @param hold_time Pointer to accept the stop condition hold period 364 * 365 * @return None 366 */ 367 void i2c_hal_get_stop_timing(i2c_hal_context_t *hal, int *setup_time, int *hold_time); 368 369 /** 370 * @brief Get the I2C scl timing configuration 371 * 372 * @param hal Context of the HAL layer 373 * @param high_period Pointer to accept the scl high period 374 * @param low_period Pointer to accept the scl low period 375 * 376 * @return None 377 */ 378 void i2c_hal_get_scl_timing(i2c_hal_context_t *hal, int *high_period, int *low_period); 379 380 /** 381 * @brief Get the I2C start timing configuration 382 * 383 * @param hal Context of the HAL layer 384 * @param setup_time Pointer to accept the start condition setup period 385 * @param hold_time Pointer to accept the start condition hold period 386 * 387 * @return None 388 */ 389 void i2c_hal_get_start_timing(i2c_hal_context_t *hal, int *setup_time, int *hold_time); 390 391 /** 392 * @brief Check if the I2C is master mode 393 * 394 * @param hal Context of the HAL layer 395 * 396 * @return True if in master mode, otherwise, false will be returned 397 */ 398 bool i2c_hal_is_master_mode(i2c_hal_context_t *hal); 399 400 /** 401 * @brief Get the rxFIFO readable length 402 * 403 * @param hal Context of the HAL layer 404 * @param len Pointer to accept the rxFIFO readable length 405 * 406 * @return None 407 */ 408 void i2c_hal_get_rxfifo_cnt(i2c_hal_context_t *hal, uint32_t *len); 409 410 /** 411 * @brief Set I2C bus timing with the given frequency 412 * 413 * @param hal Context of the HAL layer 414 * @param scl_freq The scl frequency to be set 415 * @param src_clk Source clock of I2C 416 * 417 * @return None 418 */ 419 void i2c_hal_set_bus_timing(i2c_hal_context_t *hal, int scl_freq, i2c_sclk_t src_clk); 420 421 /** 422 * @brief Get I2C txFIFO writeable length 423 * 424 * @param hal Context of the HAL layer 425 * @param len Pointer to accept the txFIFO writeable length 426 * 427 * @return None 428 */ 429 void i2c_hal_get_txfifo_cnt(i2c_hal_context_t *hal, uint32_t *len); 430 431 /** 432 * @brief Check if the I2C is master mode 433 * 434 * @param hal Context of the HAL layer 435 * @param tx_mode Pointer to accept the TX data mode 436 * @param rx_mode Pointer to accept the RX data mode 437 * 438 * @return None 439 */ 440 void i2c_hal_get_data_mode(i2c_hal_context_t *hal, i2c_trans_mode_t *tx_mode, i2c_trans_mode_t *rx_mode); 441 442 /** 443 * @brief I2C hardware FSM reset 444 * 445 * @param hal Context of the HAL layer 446 * 447 * @return None 448 */ 449 void i2c_hal_master_fsm_rst(i2c_hal_context_t *hal); 450 451 /** 452 * @brief @brief Clear I2C bus 453 * 454 * @param hal Context of the HAL layer 455 * 456 * @return None 457 */ 458 void i2c_hal_master_clr_bus(i2c_hal_context_t *hal); 459 460 /** 461 * @brief Enable I2C slave TX interrupt 462 * 463 * @param hal Context of the HAL layer 464 * 465 * @return None 466 */ 467 void i2c_hal_enable_slave_tx_it(i2c_hal_context_t *hal); 468 469 /** 470 * @brief Disable I2C slave TX interrupt 471 * 472 * @param hal Context of the HAL layer 473 * 474 * @return None 475 */ 476 void i2c_hal_disable_slave_tx_it(i2c_hal_context_t *hal); 477 478 /** 479 * @brief Enable I2C slave RX interrupt 480 * 481 * @param hal Context of the HAL layer 482 * 483 * @return None 484 */ 485 void i2c_hal_enable_slave_rx_it(i2c_hal_context_t *hal); 486 487 /** 488 * @brief Disable I2C slave RX interrupt 489 * 490 * @param hal Context of the HAL layer 491 * 492 * @return None 493 */ 494 void i2c_hal_disable_slave_rx_it(i2c_hal_context_t *hal); 495 496 /** 497 * @brief I2C master handle tx interrupt event 498 * 499 * @param hal Context of the HAL layer 500 * @param event Pointer to accept the interrupt event 501 * 502 * @return None 503 */ 504 void i2c_hal_master_handle_tx_event(i2c_hal_context_t *hal, i2c_intr_event_t *event); 505 506 /** 507 * @brief I2C master handle rx interrupt event 508 * 509 * @param hal Context of the HAL layer 510 * @param event Pointer to accept the interrupt event 511 * 512 * @return None 513 */ 514 void i2c_hal_master_handle_rx_event(i2c_hal_context_t *hal, i2c_intr_event_t *event); 515 516 /** 517 * @brief I2C slave handle interrupt event 518 * 519 * @param hal Context of the HAL layer 520 * @param event Pointer to accept the interrupt event 521 * 522 * @return None 523 */ 524 void i2c_hal_slave_handle_event(i2c_hal_context_t *hal, i2c_intr_event_t *event); 525 526 /** 527 * @brief Synchronize I2C status 528 * 529 * @param hal Context of the HAL layer 530 * 531 * @return None 532 * 533 */ 534 void i2c_hal_update_config(i2c_hal_context_t *hal); 535