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 transaction 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 Set the source clock. This function is meant to be used in 115 * slave mode, in order to select a source clock abe to handle 116 * the expected SCL frequency. 117 * 118 * @param hal Context of the HAL layer 119 * @param src_clk Source clock to use choosen from `i2c_sclk_t` type 120 */ 121 #define i2c_hal_set_source_clk(hal, src_clk) i2c_ll_set_source_clk((hal)->dev, src_clk) 122 123 /** 124 * @brief Init the I2C master. 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_master_init(i2c_hal_context_t *hal, i2c_port_t i2c_num); 132 133 /** 134 * @brief Init the I2C slave. 135 * 136 * @param hal Context of the HAL layer 137 * @param i2c_num I2C port number 138 * 139 * @return None 140 */ 141 void i2c_hal_slave_init(i2c_hal_context_t *hal, i2c_port_t i2c_num); 142 143 /** 144 * @brief Reset the I2C hw txfifo 145 * 146 * @param hal Context of the HAL layer 147 * 148 * @return None 149 */ 150 void i2c_hal_txfifo_rst(i2c_hal_context_t *hal); 151 152 /** 153 * @brief Reset the I2C hw rxfifo 154 * 155 * @param hal Context of the HAL layer 156 * 157 * @return None 158 */ 159 void i2c_hal_rxfifo_rst(i2c_hal_context_t *hal); 160 161 /** 162 * @brief Configure the I2C data MSB bit shifted first or LSB bit shifted first. 163 * 164 * @param hal Context of the HAL layer 165 * @param tx_mode Data format of TX 166 * @param rx_mode Data format of RX 167 * 168 * @return None 169 */ 170 void i2c_hal_set_data_mode(i2c_hal_context_t *hal, i2c_trans_mode_t tx_mode, i2c_trans_mode_t rx_mode); 171 172 /** 173 * @brief Configure the I2C hardware filter function. 174 * 175 * @param hal Context of the HAL layer 176 * @param filter_num If the glitch period on the line is less than this value(in APB cycle), it will be filtered out 177 * If `filter_num == 0`, the filter will be disabled 178 * 179 * @return None 180 */ 181 void i2c_hal_set_filter(i2c_hal_context_t *hal, uint8_t filter_num); 182 183 /** 184 * @brief Get the I2C hardware filter configuration 185 * 186 * @param hal Context of the HAL layer 187 * @param filter_num Pointer to accept the hardware filter configuration 188 * 189 * @return None 190 */ 191 void i2c_hal_get_filter(i2c_hal_context_t *hal, uint8_t *filter_num); 192 193 /** 194 * @brief Configure the I2C SCL timing 195 * 196 * @param hal Context of the HAL layer 197 * @param hight_period SCL high period 198 * @param low_period SCL low period 199 * 200 * @return None 201 */ 202 void i2c_hal_set_scl_timing(i2c_hal_context_t *hal, int hight_period, int low_period); 203 204 /** 205 * @brief Configure the I2C master SCL frequency 206 * 207 * @param hal Context of the HAL layer 208 * @param src_clk The I2C Source clock frequency 209 * @param scl_freq The SCL frequency to be set 210 * 211 * @return None 212 */ 213 void i2c_hal_set_scl_freq(i2c_hal_context_t *hal, uint32_t src_clk, uint32_t scl_freq); 214 215 /** 216 * @brief Clear the I2C interrupt status with the given mask 217 * 218 * @param hal Context of the HAL layer 219 * @param mask The interrupt bitmap needs to be clearned 220 * 221 * @return None 222 */ 223 void i2c_hal_clr_intsts_mask(i2c_hal_context_t *hal, uint32_t mask); 224 225 /** 226 * @brief Enable 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 enabled 230 * 231 * @return None 232 */ 233 void i2c_hal_enable_intr_mask(i2c_hal_context_t *hal, uint32_t mask); 234 235 /** 236 * @brief Disable the I2C interrupt with the given mask 237 * 238 * @param hal Context of the HAL layer 239 * @param mask The interrupt bitmap needs to be disabled 240 * 241 * @return None 242 */ 243 void i2c_hal_disable_intr_mask(i2c_hal_context_t *hal, uint32_t mask); 244 245 /** 246 * @brief Configure the I2C memory access mode, FIFO mode or none FIFO mode 247 * 248 * @param hal Context of the HAL layer 249 * @param fifo_mode_en Set true to enable FIFO access mode, else set it false 250 * 251 * @return None 252 */ 253 void i2c_hal_set_fifo_mode(i2c_hal_context_t *hal, bool fifo_mode_en); 254 255 /** 256 * @brief Configure the I2C timeout value 257 * 258 * @param hal Context of the HAL layer 259 * @param tout_val the timeout value to be set 260 * 261 * @return None 262 */ 263 void i2c_hal_set_tout(i2c_hal_context_t *hal, int tout_val); 264 265 /** 266 * @brief Configure the I2C timeout value 267 * 268 * @param hal Context of the HAL layer 269 * @param tout_val the timeout value to be set 270 * 271 * @return None 272 */ 273 void i2c_hal_set_tout_en(i2c_hal_context_t *hal, bool tout_en); 274 275 /** 276 * @brief Get the I2C time out configuration 277 * 278 * @param tout_val Pointer to accept the timeout configuration 279 * 280 * @return None 281 */ 282 void i2c_hal_get_tout(i2c_hal_context_t *hal, int *tout_val); 283 284 /** 285 * @brief Configure the I2C slave address 286 * 287 * @param hal Context of the HAL layer 288 * @param slave_addr Slave address 289 * @param addr_10bit_en Set true to enable 10-bit slave address mode, Set false to enable 7-bit address mode 290 * 291 * @return None 292 */ 293 void i2c_hal_set_slave_addr(i2c_hal_context_t *hal, uint16_t slave_addr, bool addr_10bit_en); 294 295 /** 296 * @brief Configure the I2C stop timing 297 * 298 * @param hal Context of the HAL layer 299 * @param stop_setup The stop condition setup period (in APB cycle) 300 * @param stop_hold The stop condition hold period (in APB cycle) 301 * 302 * @return None 303 */ 304 void i2c_hal_set_stop_timing(i2c_hal_context_t *hal, int stop_setup, int stop_hold); 305 306 /** 307 * @brief Configure the I2C start timing 308 * 309 * @param hal Context of the HAL layer 310 * @param start_setup The start condition setup period (in APB cycle) 311 * @param start_hold The start condition hold period (in APB cycle) 312 * 313 * @return None 314 */ 315 void i2c_hal_set_start_timing(i2c_hal_context_t *hal, int start_setup, int start_hold); 316 317 /** 318 * @brief Configure the I2C sda sample timing 319 * 320 * @param hal Context of the HAL layer 321 * @param sda_sample The SDA sample time (in APB cycle) 322 * @param sda_hold The SDA hold time (in APB cycle) 323 * 324 * @return None 325 */ 326 void i2c_hal_set_sda_timing(i2c_hal_context_t *hal, int sda_sample, int sda_hold); 327 328 /** 329 * @brief Configure the I2C txfifo empty threshold value 330 * 331 * @param hal Context of the HAL layer. 332 * @param empty_thr TxFIFO empty threshold value 333 * 334 * @return None 335 */ 336 void i2c_hal_set_txfifo_empty_thr(i2c_hal_context_t *hal, uint8_t empty_thr); 337 338 /** 339 * @brief Configure the I2C rxfifo full threshold value 340 * 341 * @param hal Context of the HAL layer 342 * @param full_thr RxFIFO full threshold value 343 * 344 * @return None 345 */ 346 void i2c_hal_set_rxfifo_full_thr(i2c_hal_context_t *hal, uint8_t full_thr); 347 348 /** 349 * @brief Get the I2C interrupt status 350 * 351 * @param hal Context of the HAL layer 352 * @param mask Pointer to accept the interrupt status 353 * 354 * @return None 355 */ 356 void i2c_hal_get_intsts_mask(i2c_hal_context_t *hal, uint32_t *mask); 357 358 /** 359 * @brief Check if the I2C bus is busy 360 * 361 * @param hal Context of the HAL layer 362 * 363 * @return True if the bus is busy, otherwise, fale will be returned 364 */ 365 bool i2c_hal_is_bus_busy(i2c_hal_context_t *hal); 366 367 /** 368 * @brief Get the I2C sda sample timing configuration 369 * 370 * @param hal Context of the HAL layer 371 * @param sample_time Pointer to accept the SDA sample time 372 * @param hold_time Pointer to accept the SDA hold time 373 * 374 * @return None 375 */ 376 void i2c_hal_get_sda_timing(i2c_hal_context_t *hal, int *sample_time, int *hold_time); 377 378 /** 379 * @brief Get the I2C stop timing configuration 380 * 381 * @param hal Context of the HAL layer 382 * @param setup_time Pointer to accept the stop condition setup period 383 * @param hold_time Pointer to accept the stop condition hold period 384 * 385 * @return None 386 */ 387 void i2c_hal_get_stop_timing(i2c_hal_context_t *hal, int *setup_time, int *hold_time); 388 389 /** 390 * @brief Get the I2C scl timing configuration 391 * 392 * @param hal Context of the HAL layer 393 * @param high_period Pointer to accept the scl high period 394 * @param low_period Pointer to accept the scl low period 395 * 396 * @return None 397 */ 398 void i2c_hal_get_scl_timing(i2c_hal_context_t *hal, int *high_period, int *low_period); 399 400 /** 401 * @brief Get the I2C start timing configuration 402 * 403 * @param hal Context of the HAL layer 404 * @param setup_time Pointer to accept the start condition setup period 405 * @param hold_time Pointer to accept the start condition hold period 406 * 407 * @return None 408 */ 409 void i2c_hal_get_start_timing(i2c_hal_context_t *hal, int *setup_time, int *hold_time); 410 411 /** 412 * @brief Check if the I2C is master mode 413 * 414 * @param hal Context of the HAL layer 415 * 416 * @return True if in master mode, otherwise, false will be returned 417 */ 418 bool i2c_hal_is_master_mode(i2c_hal_context_t *hal); 419 420 /** 421 * @brief Get the rxFIFO readable length 422 * 423 * @param hal Context of the HAL layer 424 * @param len Pointer to accept the rxFIFO readable length 425 * 426 * @return None 427 */ 428 void i2c_hal_get_rxfifo_cnt(i2c_hal_context_t *hal, uint32_t *len); 429 430 /** 431 * @brief Set I2C bus timing with the given frequency 432 * 433 * @param hal Context of the HAL layer 434 * @param scl_freq The scl frequency to be set 435 * @param src_clk Source clock of I2C 436 * 437 * @return None 438 */ 439 void i2c_hal_set_bus_timing(i2c_hal_context_t *hal, int scl_freq, i2c_sclk_t src_clk); 440 441 /** 442 * @brief Get I2C txFIFO writeable length 443 * 444 * @param hal Context of the HAL layer 445 * @param len Pointer to accept the txFIFO writeable length 446 * 447 * @return None 448 */ 449 void i2c_hal_get_txfifo_cnt(i2c_hal_context_t *hal, uint32_t *len); 450 451 /** 452 * @brief Check if the I2C is master mode 453 * 454 * @param hal Context of the HAL layer 455 * @param tx_mode Pointer to accept the TX data mode 456 * @param rx_mode Pointer to accept the RX data mode 457 * 458 * @return None 459 */ 460 void i2c_hal_get_data_mode(i2c_hal_context_t *hal, i2c_trans_mode_t *tx_mode, i2c_trans_mode_t *rx_mode); 461 462 /** 463 * @brief I2C hardware FSM reset 464 * 465 * @param hal Context of the HAL layer 466 * 467 * @return None 468 */ 469 void i2c_hal_master_fsm_rst(i2c_hal_context_t *hal); 470 471 /** 472 * @brief @brief Clear I2C bus 473 * 474 * @param hal Context of the HAL layer 475 * 476 * @return None 477 */ 478 void i2c_hal_master_clr_bus(i2c_hal_context_t *hal); 479 480 /** 481 * @brief Enable I2C slave TX interrupt 482 * 483 * @param hal Context of the HAL layer 484 * 485 * @return None 486 */ 487 void i2c_hal_enable_slave_tx_it(i2c_hal_context_t *hal); 488 489 /** 490 * @brief Disable I2C slave TX interrupt 491 * 492 * @param hal Context of the HAL layer 493 * 494 * @return None 495 */ 496 void i2c_hal_disable_slave_tx_it(i2c_hal_context_t *hal); 497 498 /** 499 * @brief Enable I2C slave RX interrupt 500 * 501 * @param hal Context of the HAL layer 502 * 503 * @return None 504 */ 505 void i2c_hal_enable_slave_rx_it(i2c_hal_context_t *hal); 506 507 /** 508 * @brief Disable I2C slave RX interrupt 509 * 510 * @param hal Context of the HAL layer 511 * 512 * @return None 513 */ 514 void i2c_hal_disable_slave_rx_it(i2c_hal_context_t *hal); 515 516 /** 517 * @brief I2C master handle tx 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_master_handle_tx_event(i2c_hal_context_t *hal, i2c_intr_event_t *event); 525 526 /** 527 * @brief I2C master handle rx interrupt event 528 * 529 * @param hal Context of the HAL layer 530 * @param event Pointer to accept the interrupt event 531 * 532 * @return None 533 */ 534 void i2c_hal_master_handle_rx_event(i2c_hal_context_t *hal, i2c_intr_event_t *event); 535 536 /** 537 * @brief I2C slave handle interrupt event 538 * 539 * @param hal Context of the HAL layer 540 * @param event Pointer to accept the interrupt event 541 * 542 * @return None 543 */ 544 void i2c_hal_slave_handle_event(i2c_hal_context_t *hal, i2c_intr_event_t *event); 545 546 /** 547 * @brief Synchronize I2C status 548 * 549 * @param hal Context of the HAL layer 550 * 551 * @return None 552 * 553 */ 554 void i2c_hal_update_config(i2c_hal_context_t *hal); 555
