From deb91c7abe8b1fafc5e9410fd2fdfd2aeebcea57 Mon Sep 17 00:00:00 2001
From: "C.S.M" <caosenmiao@espressif.com>
Date: Thu, 22 Aug 2024 16:20:29 +0800
Subject: [PATCH 1/4] fix(i2c_master): Fix an I2C issue that slave streth
 happen but master timeout set seems doesn't work

Closes https://github.com/espressif/esp-idf/issues/14129
Closes https://github.com/espressif/esp-idf/issues/14401
---
 components/esp_driver_i2c/i2c_master.c      | 33 ++++++++++++---------
 components/hal/esp32c2/include/hal/i2c_ll.h | 13 ++++----
 components/hal/esp32c3/include/hal/i2c_ll.h | 15 +++++-----
 components/hal/esp32c5/include/hal/i2c_ll.h | 13 ++++----
 components/hal/esp32c6/include/hal/i2c_ll.h |  5 ++--
 components/hal/esp32h2/include/hal/i2c_ll.h | 15 +++++-----
 components/hal/esp32p4/include/hal/i2c_ll.h | 15 +++++-----
 components/hal/esp32s3/include/hal/i2c_ll.h | 13 ++++----
 8 files changed, 67 insertions(+), 55 deletions(-)

diff --git a/components/esp_driver_i2c/i2c_master.c b/components/esp_driver_i2c/i2c_master.c
index 34a7106ef9..98ad47b8b9 100644
--- a/components/esp_driver_i2c/i2c_master.c
+++ b/components/esp_driver_i2c/i2c_master.c
@@ -46,6 +46,8 @@ static const char *TAG = "i2c.master";
 #define I2C_FIFO_LEN(port_num) (SOC_I2C_FIFO_LEN)
 #endif
 
+#define I2C_CLR_BUS_TIMEOUT_MS        (50)  // 50ms is sufficient for clearing the bus
+
 static esp_err_t s_i2c_master_clear_bus(i2c_bus_handle_t handle)
 {
 #if !SOC_I2C_SUPPORT_HW_CLR_BUS
@@ -554,23 +556,13 @@ static esp_err_t s_i2c_transaction_start(i2c_master_dev_handle_t i2c_dev, int xf
     i2c_master->rx_cnt = 0;
     i2c_master->read_len_static = 0;
 
-    i2c_hal_master_set_scl_timeout_val(hal, i2c_dev->scl_wait_us, i2c_master->base->clk_src_freq_hz);
-
-    if (!i2c_master->base->is_lp_i2c) {
-        I2C_CLOCK_SRC_ATOMIC() {
-            i2c_ll_set_source_clk(hal->dev, i2c_master->base->clk_src);
-        }
-    }
-#if SOC_LP_I2C_SUPPORTED
-    else {
-        LP_I2C_SRC_CLK_ATOMIC() {
-            lp_i2c_ll_set_source_clk(hal->dev, i2c_master->base->clk_src);
-        }
-    }
-#endif
     I2C_CLOCK_SRC_ATOMIC() {
         i2c_hal_set_bus_timing(hal, i2c_dev->scl_speed_hz, i2c_master->base->clk_src, i2c_master->base->clk_src_freq_hz);
     }
+
+    // Set the timeout value
+    i2c_hal_master_set_scl_timeout_val(hal, i2c_dev->scl_wait_us, i2c_master->base->clk_src_freq_hz);
+
     i2c_ll_master_set_fractional_divider(hal->dev, 0, 0);
     i2c_ll_update(hal->dev);
 
@@ -909,6 +901,19 @@ esp_err_t i2c_new_master_bus(const i2c_master_bus_config_t *bus_config, i2c_mast
     }
     ESP_GOTO_ON_ERROR(i2c_param_master_config(i2c_master->base, bus_config), err, TAG, "i2c configure parameter failed");
 
+    if (!i2c_master->base->is_lp_i2c) {
+        I2C_CLOCK_SRC_ATOMIC() {
+            i2c_ll_set_source_clk(hal->dev, i2c_master->base->clk_src);
+        }
+    }
+#if SOC_LP_I2C_SUPPORTED
+    else {
+        LP_I2C_SRC_CLK_ATOMIC() {
+            lp_i2c_ll_set_source_clk(hal->dev, i2c_master->base->clk_src);
+        }
+    }
+#endif
+
     i2c_master->bus_lock_mux = xSemaphoreCreateBinaryWithCaps(I2C_MEM_ALLOC_CAPS);
     ESP_GOTO_ON_FALSE(i2c_master->bus_lock_mux, ESP_ERR_NO_MEM, err, TAG, "No memory for binary semaphore");
     xSemaphoreGive(i2c_master->bus_lock_mux);
diff --git a/components/hal/esp32c2/include/hal/i2c_ll.h b/components/hal/esp32c2/include/hal/i2c_ll.h
index bc6ae54802..1d43bce85a 100644
--- a/components/hal/esp32c2/include/hal/i2c_ll.h
+++ b/components/hal/esp32c2/include/hal/i2c_ll.h
@@ -583,7 +583,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -647,7 +647,7 @@ static inline void i2c_ll_master_get_filter(i2c_dev_t *hw, uint8_t *filter_conf)
 }
 
 /**
- * @brief Reste I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
+ * @brief reset I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
  *
  * @param  hw Beginning address of the peripheral registers
  *
@@ -675,7 +675,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
     hw->scl_sp_conf.scl_rst_slv_en = 1;
     hw->ctr.conf_upgate = 1;
-    // hardward will clear scl_rst_slv_en after sending SCL pulses,
+    // hardware will clear scl_rst_slv_en after sending SCL pulses,
     // and we should set conf_upgate bit to synchronize register value.
     while (hw->scl_sp_conf.scl_rst_slv_en);
     hw->ctr.conf_upgate = 1;
@@ -756,7 +756,8 @@ static inline bool i2c_ll_master_is_cmd_done(i2c_dev_t *hw, int cmd_idx)
 static inline uint32_t i2c_ll_calculate_timeout_us_to_reg_val(uint32_t src_clk_hz, uint32_t timeout_us)
 {
     uint32_t clk_cycle_num_per_us = src_clk_hz / (1 * 1000 * 1000);
-    return 31 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
+    // round up to an integer
+    return 32 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
 }
 
 //////////////////////////////////////////Deprecated Functions//////////////////////////////////////////////////////////
@@ -791,7 +792,7 @@ typedef enum {
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -906,7 +907,7 @@ static inline void i2c_ll_master_disable_rx_it(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  hight_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  hight_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  *
  * @return None.
diff --git a/components/hal/esp32c3/include/hal/i2c_ll.h b/components/hal/esp32c3/include/hal/i2c_ll.h
index 9fd18c694f..4c5faed2c4 100644
--- a/components/hal/esp32c3/include/hal/i2c_ll.h
+++ b/components/hal/esp32c3/include/hal/i2c_ll.h
@@ -663,7 +663,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -698,7 +698,7 @@ static inline void i2c_ll_read_rxfifo(i2c_dev_t *hw, uint8_t *ptr, uint8_t len)
  * @param  hw Beginning address of the peripheral registers
  * @param  ram_offset Offset value of I2C RAM.
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  */
 static inline void i2c_ll_write_by_nonfifo(i2c_dev_t *hw, uint8_t ram_offset, const uint8_t *ptr, uint8_t len)
 {
@@ -770,7 +770,7 @@ static inline void i2c_ll_master_get_filter(i2c_dev_t *hw, uint8_t *filter_conf)
 }
 
 /**
- * @brief Reste I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
+ * @brief reset I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
  *
  * @param  hw Beginning address of the peripheral registers
  *
@@ -798,7 +798,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
     hw->scl_sp_conf.scl_rst_slv_en = 1;
     hw->ctr.conf_upgate = 1;
-    // hardward will clear scl_rst_slv_en after sending SCL pulses,
+    // hardware will clear scl_rst_slv_en after sending SCL pulses,
     // and we should set conf_upgate bit to synchronize register value.
     while (hw->scl_sp_conf.scl_rst_slv_en);
     hw->ctr.conf_upgate = 1;
@@ -929,7 +929,8 @@ static inline bool i2c_ll_master_is_cmd_done(i2c_dev_t *hw, int cmd_idx)
 static inline uint32_t i2c_ll_calculate_timeout_us_to_reg_val(uint32_t src_clk_hz, uint32_t timeout_us)
 {
     uint32_t clk_cycle_num_per_us = src_clk_hz / (1 * 1000 * 1000);
-    return 31 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
+    // round up to an integer
+    return 32 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
 }
 
 //////////////////////////////////////////Deprecated Functions//////////////////////////////////////////////////////////
@@ -968,7 +969,7 @@ typedef enum {
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -1155,7 +1156,7 @@ static inline void i2c_ll_slave_disable_rx_it(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  hight_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  hight_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  *
  * @return None.
diff --git a/components/hal/esp32c5/include/hal/i2c_ll.h b/components/hal/esp32c5/include/hal/i2c_ll.h
index 5bff9a3302..fbb4022f6d 100644
--- a/components/hal/esp32c5/include/hal/i2c_ll.h
+++ b/components/hal/esp32c5/include/hal/i2c_ll.h
@@ -611,7 +611,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -646,7 +646,7 @@ static inline void i2c_ll_read_rxfifo(i2c_dev_t *hw, uint8_t *ptr, uint8_t len)
  * @param  hw Beginning address of the peripheral registers
  * @param  ram_offset Offset value of I2C RAM.
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  */
 static inline void i2c_ll_write_by_nonfifo(i2c_dev_t *hw, uint8_t ram_offset, const uint8_t *ptr, uint8_t len)
 {
@@ -746,7 +746,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
     hw->scl_sp_conf.scl_rst_slv_en = 1;
     hw->ctr.conf_upgate = 1;
-    // hardward will clear scl_rst_slv_en after sending SCL pulses,
+    // hardware will clear scl_rst_slv_en after sending SCL pulses,
     // and we should set conf_upgate bit to synchronize register value.
     while (hw->scl_sp_conf.scl_rst_slv_en);
     hw->ctr.conf_upgate = 1;
@@ -863,7 +863,8 @@ static inline void i2c_ll_slave_clear_stretch(i2c_dev_t *dev)
 static inline uint32_t i2c_ll_calculate_timeout_us_to_reg_val(uint32_t src_clk_hz, uint32_t timeout_us)
 {
     uint32_t clk_cycle_num_per_us = src_clk_hz / (1 * 1000 * 1000);
-    return 31 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
+    // round up to an integer
+    return 32 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
 }
 
 //////////////////////////////////////////Deprecated Functions//////////////////////////////////////////////////////////
@@ -902,7 +903,7 @@ typedef enum {
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL high period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -1090,7 +1091,7 @@ static inline void i2c_ll_slave_disable_rx_it(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  hight_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  hight_period The I2C SCL high period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  *
  * @return None.
diff --git a/components/hal/esp32c6/include/hal/i2c_ll.h b/components/hal/esp32c6/include/hal/i2c_ll.h
index 5d0ce895d3..3bd42d6038 100644
--- a/components/hal/esp32c6/include/hal/i2c_ll.h
+++ b/components/hal/esp32c6/include/hal/i2c_ll.h
@@ -734,7 +734,7 @@ static inline void i2c_ll_master_get_filter(i2c_dev_t *hw, uint8_t *filter_conf)
 }
 
 /**
- * @brief Reste I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
+ * @brief reset I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
  *
  * @param  hw Beginning address of the peripheral registers
  *
@@ -972,7 +972,8 @@ static inline bool i2c_ll_master_is_cmd_done(i2c_dev_t *hw, int cmd_idx)
 static inline uint32_t i2c_ll_calculate_timeout_us_to_reg_val(uint32_t src_clk_hz, uint32_t timeout_us)
 {
     uint32_t clk_cycle_num_per_us = src_clk_hz / (1 * 1000 * 1000);
-    return 31 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
+    // round up to an integer
+    return 32 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
 }
 
 //////////////////////////////////////////Deprecated Functions//////////////////////////////////////////////////////////
diff --git a/components/hal/esp32h2/include/hal/i2c_ll.h b/components/hal/esp32h2/include/hal/i2c_ll.h
index 9935228463..8e9870c944 100644
--- a/components/hal/esp32h2/include/hal/i2c_ll.h
+++ b/components/hal/esp32h2/include/hal/i2c_ll.h
@@ -613,7 +613,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -648,7 +648,7 @@ static inline void i2c_ll_read_rxfifo(i2c_dev_t *hw, uint8_t *ptr, uint8_t len)
  * @param  hw Beginning address of the peripheral registers
  * @param  ram_offset Offset value of I2C RAM.
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  */
 static inline void i2c_ll_write_by_nonfifo(i2c_dev_t *hw, uint8_t ram_offset, const uint8_t *ptr, uint8_t len)
 {
@@ -720,7 +720,7 @@ static inline void i2c_ll_master_get_filter(i2c_dev_t *hw, uint8_t *filter_conf)
 }
 
 /**
- * @brief Reste I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
+ * @brief reset I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
  *
  * @param  hw Beginning address of the peripheral registers
  *
@@ -748,7 +748,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
     hw->scl_sp_conf.scl_rst_slv_en = 1;
     hw->ctr.conf_upgate = 1;
-    // hardward will clear scl_rst_slv_en after sending SCL pulses,
+    // hardware will clear scl_rst_slv_en after sending SCL pulses,
     // and we should set conf_upgate bit to synchronize register value.
     while (hw->scl_sp_conf.scl_rst_slv_en);
     hw->ctr.conf_upgate = 1;
@@ -879,7 +879,8 @@ static inline bool i2c_ll_master_is_cmd_done(i2c_dev_t *hw, int cmd_idx)
 static inline uint32_t i2c_ll_calculate_timeout_us_to_reg_val(uint32_t src_clk_hz, uint32_t timeout_us)
 {
     uint32_t clk_cycle_num_per_us = src_clk_hz / (1 * 1000 * 1000);
-    return 31 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
+    // round up to an integer
+    return 32 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
 }
 
 //////////////////////////////////////////Deprecated Functions//////////////////////////////////////////////////////////
@@ -918,7 +919,7 @@ typedef enum {
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -1106,7 +1107,7 @@ static inline void i2c_ll_slave_disable_rx_it(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  hight_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  hight_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  *
  * @return None.
diff --git a/components/hal/esp32p4/include/hal/i2c_ll.h b/components/hal/esp32p4/include/hal/i2c_ll.h
index e4fdb1622b..9693707256 100644
--- a/components/hal/esp32p4/include/hal/i2c_ll.h
+++ b/components/hal/esp32p4/include/hal/i2c_ll.h
@@ -615,7 +615,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -650,7 +650,7 @@ static inline void i2c_ll_read_rxfifo(i2c_dev_t *hw, uint8_t *ptr, uint8_t len)
  * @param  hw Beginning address of the peripheral registers
  * @param  ram_offset Offset value of I2C RAM.
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  */
 static inline void i2c_ll_write_by_nonfifo(i2c_dev_t *hw, uint8_t ram_offset, const uint8_t *ptr, uint8_t len)
 {
@@ -722,7 +722,7 @@ static inline void i2c_ll_master_get_filter(i2c_dev_t *hw, uint8_t *filter_conf)
 }
 
 /**
- * @brief Reste I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
+ * @brief reset I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
  *
  * @param  hw Beginning address of the peripheral registers
  *
@@ -750,7 +750,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
     hw->scl_sp_conf.scl_rst_slv_en = 1;
     hw->ctr.conf_upgate = 1;
-    // hardward will clear scl_rst_slv_en after sending SCL pulses,
+    // hardware will clear scl_rst_slv_en after sending SCL pulses,
     // and we should set conf_upgate bit to synchronize register value.
     while (hw->scl_sp_conf.scl_rst_slv_en);
     hw->ctr.conf_upgate = 1;
@@ -976,7 +976,8 @@ static inline bool i2c_ll_master_is_cmd_done(i2c_dev_t *hw, int cmd_idx)
 static inline uint32_t i2c_ll_calculate_timeout_us_to_reg_val(uint32_t src_clk_hz, uint32_t timeout_us)
 {
     uint32_t clk_cycle_num_per_us = src_clk_hz / (1 * 1000 * 1000);
-    return 31 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
+    // round up to an integer
+    return 32 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
 }
 
 //////////////////////////////////////////Deprecated Functions//////////////////////////////////////////////////////////
@@ -1015,7 +1016,7 @@ typedef enum {
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -1203,7 +1204,7 @@ static inline void i2c_ll_slave_disable_rx_it(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  hight_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  hight_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  *
  * @return None.
diff --git a/components/hal/esp32s3/include/hal/i2c_ll.h b/components/hal/esp32s3/include/hal/i2c_ll.h
index d881c05416..caf58b9022 100644
--- a/components/hal/esp32s3/include/hal/i2c_ll.h
+++ b/components/hal/esp32s3/include/hal/i2c_ll.h
@@ -671,7 +671,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -706,7 +706,7 @@ static inline void i2c_ll_read_rxfifo(i2c_dev_t *hw, uint8_t *ptr, uint8_t len)
  * @param  hw Beginning address of the peripheral registers
  * @param  ram_offset Offset value of I2C RAM.
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  */
 static inline void i2c_ll_write_by_nonfifo(i2c_dev_t *hw, uint8_t ram_offset, const uint8_t *ptr, uint8_t len)
 {
@@ -778,7 +778,7 @@ static inline void i2c_ll_master_get_filter(i2c_dev_t *hw, uint8_t *filter_conf)
 }
 
 /**
- * @brief Reste I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
+ * @brief reset I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
  *
  * @param  hw Beginning address of the peripheral registers
  *
@@ -931,7 +931,8 @@ static inline bool i2c_ll_master_is_cmd_done(i2c_dev_t *hw, int cmd_idx)
 static inline uint32_t i2c_ll_calculate_timeout_us_to_reg_val(uint32_t src_clk_hz, uint32_t timeout_us)
 {
     uint32_t clk_cycle_num_per_us = src_clk_hz / (1 * 1000 * 1000);
-    return 31 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
+    // round up to an integer
+    return 32 - __builtin_clz(clk_cycle_num_per_us * timeout_us);
 }
 
 //////////////////////////////////////////Deprecated Functions//////////////////////////////////////////////////////////
@@ -986,7 +987,7 @@ static inline void i2c_ll_get_scl_clk_timing(i2c_dev_t *hw, int *high_period, in
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -1157,7 +1158,7 @@ static inline void i2c_ll_slave_disable_rx_it(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL height period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  *
  * @return None.

From 189db78bec83ada18ddced7f24a63ac3b87b48ec Mon Sep 17 00:00:00 2001
From: "C.S.M" <caosenmiao@espressif.com>
Date: Wed, 28 Aug 2024 18:21:28 +0800
Subject: [PATCH 2/4] fix(i2c): Fix possible error state in clear the bus,

Closes https://github.com/espressif/esp-idf/issues/13647
---
 components/driver/i2c/i2c.c                 |  5 +++-
 components/esp_driver_i2c/i2c_master.c      | 28 ++++++++++++++++-----
 components/hal/esp32/include/hal/i2c_ll.h   | 24 +++++++++++++-----
 components/hal/esp32c2/include/hal/i2c_ll.h | 21 ++++++++++++----
 components/hal/esp32c3/include/hal/i2c_ll.h | 21 ++++++++++++----
 components/hal/esp32c5/include/hal/i2c_ll.h | 21 ++++++++++++----
 components/hal/esp32c6/include/hal/i2c_ll.h | 21 ++++++++++++----
 components/hal/esp32h2/include/hal/i2c_ll.h | 21 ++++++++++++----
 components/hal/esp32p4/include/hal/i2c_ll.h | 21 ++++++++++++----
 components/hal/esp32s2/include/hal/i2c_ll.h | 23 +++++++++++++----
 components/hal/esp32s3/include/hal/i2c_ll.h | 15 ++++++++++-
 11 files changed, 172 insertions(+), 49 deletions(-)

diff --git a/components/driver/i2c/i2c.c b/components/driver/i2c/i2c.c
index eb315a4ec4..12f2a25d7b 100644
--- a/components/driver/i2c/i2c.c
+++ b/components/driver/i2c/i2c.c
@@ -684,7 +684,10 @@ static esp_err_t i2c_master_clear_bus(i2c_port_t i2c_num)
     gpio_set_level(sda_io, 1); // STOP, SDA low -> high while SCL is HIGH
     i2c_set_pin(i2c_num, sda_io, scl_io, 1, 1, I2C_MODE_MASTER);
 #else
-    i2c_ll_master_clr_bus(i2c_context[i2c_num].hal.dev, I2C_CLR_BUS_SCL_NUM);
+    i2c_ll_master_clr_bus(i2c_context[i2c_num].hal.dev, I2C_CLR_BUS_SCL_NUM, true);
+    while (i2c_ll_master_is_bus_clear_done(i2c_context[i2c_num].hal.dev)) {
+    }
+    i2c_ll_update(i2c_context[i2c_num].hal.dev);
 #endif
     return ESP_OK;
 }
diff --git a/components/esp_driver_i2c/i2c_master.c b/components/esp_driver_i2c/i2c_master.c
index 98ad47b8b9..5fed674d78 100644
--- a/components/esp_driver_i2c/i2c_master.c
+++ b/components/esp_driver_i2c/i2c_master.c
@@ -50,6 +50,7 @@ static const char *TAG = "i2c.master";
 
 static esp_err_t s_i2c_master_clear_bus(i2c_bus_handle_t handle)
 {
+    esp_err_t ret = ESP_OK;
 #if !SOC_I2C_SUPPORT_HW_CLR_BUS
     const int scl_half_period = 5; // use standard 100kHz data rate
     int i = 0;
@@ -76,9 +77,23 @@ static esp_err_t s_i2c_master_clear_bus(i2c_bus_handle_t handle)
     i2c_common_set_pins(handle);
 #else
     i2c_hal_context_t *hal = &handle->hal;
-    i2c_ll_master_clr_bus(hal->dev, I2C_LL_RESET_SLV_SCL_PULSE_NUM_DEFAULT);
+    i2c_ll_master_clr_bus(hal->dev, I2C_LL_RESET_SLV_SCL_PULSE_NUM_DEFAULT, true);
+    // If the i2c master clear bus state machine got disturbed when its work, it would go into error state.
+    // The solution here is to use freertos tick counter to set time threshold. If its not return on time,
+    // return invalid state and turn off the state machine for avoiding its always wrong.
+    TickType_t start_tick = xTaskGetTickCount();
+    const TickType_t timeout_ticks = pdMS_TO_TICKS(I2C_CLR_BUS_TIMEOUT_MS);
+    while (i2c_ll_master_is_bus_clear_done(hal->dev)) {
+        if ((xTaskGetTickCount() - start_tick) > timeout_ticks) {
+            ESP_LOGE(TAG, "clear bus failed.");
+            i2c_ll_master_clr_bus(hal->dev, 0, false);
+            ret = ESP_ERR_INVALID_STATE;
+            break;
+        }
+    }
+    i2c_ll_update(hal->dev);
 #endif
-    return ESP_OK;
+    return ret;
 }
 
 /**
@@ -90,6 +105,7 @@ static esp_err_t s_i2c_master_clear_bus(i2c_bus_handle_t handle)
  */
 static esp_err_t s_i2c_hw_fsm_reset(i2c_master_bus_handle_t i2c_master)
 {
+    esp_err_t ret = ESP_OK;
     i2c_hal_context_t *hal = &i2c_master->base->hal;
 #if !SOC_I2C_SUPPORT_HW_FSM_RST
     i2c_hal_timing_config_t timing_config;
@@ -99,7 +115,7 @@ static esp_err_t s_i2c_hw_fsm_reset(i2c_master_bus_handle_t i2c_master)
     i2c_ll_master_get_filter(hal->dev, &filter_cfg);
 
     //to reset the I2C hw module, we need re-enable the hw
-    s_i2c_master_clear_bus(i2c_master->base);
+    ret = s_i2c_master_clear_bus(i2c_master->base);
     I2C_RCC_ATOMIC() {
         i2c_ll_reset_register(i2c_master->base->port_num);
     }
@@ -111,9 +127,9 @@ static esp_err_t s_i2c_hw_fsm_reset(i2c_master_bus_handle_t i2c_master)
     i2c_ll_master_set_filter(hal->dev, filter_cfg);
 #else
     i2c_ll_master_fsm_rst(hal->dev);
-    s_i2c_master_clear_bus(i2c_master->base);
+    ret = s_i2c_master_clear_bus(i2c_master->base);
 #endif
-    return ESP_OK;
+    return ret;
 }
 
 static void s_i2c_err_log_print(i2c_master_event_t event, bool bypass_nack_log)
@@ -542,7 +558,7 @@ static esp_err_t s_i2c_transaction_start(i2c_master_dev_handle_t i2c_dev, int xf
     // Sometimes when the FSM get stuck, the ACK_ERR interrupt will occur endlessly until we reset the FSM and clear bus.
     esp_err_t ret = ESP_OK;
     if (i2c_master->status == I2C_STATUS_TIMEOUT || i2c_ll_is_bus_busy(hal->dev)) {
-        s_i2c_hw_fsm_reset(i2c_master);
+        ESP_RETURN_ON_ERROR(s_i2c_hw_fsm_reset(i2c_master), TAG, "reset hardware failed");
     }
 
     if (i2c_master->base->pm_lock) {
diff --git a/components/hal/esp32/include/hal/i2c_ll.h b/components/hal/esp32/include/hal/i2c_ll.h
index b56e9c0200..dc6a4be60d 100644
--- a/components/hal/esp32/include/hal/i2c_ll.h
+++ b/components/hal/esp32/include/hal/i2c_ll.h
@@ -106,7 +106,7 @@ static inline void i2c_ll_master_set_bus_timing(i2c_dev_t *hw, i2c_hal_clk_confi
     /* SCL period. According to the TRM, we should always subtract 1 to SCL low period */
     HAL_ASSERT(bus_cfg->scl_low > 0);
     hw->scl_low_period.period = bus_cfg->scl_low - 1;
-    /* Still according to the TRM, if filter is not enbled, we have to subtract 7,
+    /* Still according to the TRM, if filter is not enabled, we have to subtract 7,
      * if SCL filter is enabled, we have to subtract:
      *   8 if SCL filter is between 0 and 2 (included)
      *   6 + SCL threshold if SCL filter is between 3 and 7 (included)
@@ -547,7 +547,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -612,7 +612,7 @@ static inline void i2c_ll_master_get_filter(i2c_dev_t *hw, uint8_t *filter_conf)
 }
 
 /**
- * @brief Reste I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
+ * @brief Reset I2C master FSM. When the master FSM is stuck, call this function to reset the FSM
  *
  * @param  hw Beginning address of the peripheral registers
  *
@@ -633,11 +633,23 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     ;//ESP32 do not support
 }
 
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return true;
+}
+
 /**
  * @brief Set I2C source clock
  *
@@ -875,7 +887,7 @@ static inline void i2c_ll_get_scl_clk_timing(i2c_dev_t *hw, int *high_period, in
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL high period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -1058,7 +1070,7 @@ static inline uint32_t i2c_ll_get_hw_version(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  hight_period The I2C SCL hight period (in APB cycle)
+ * @param  hight_period The I2C SCL high period (in APB cycle)
  * @param  low_period The I2C SCL low period (in APB cycle)
  *
  * @return None.
diff --git a/components/hal/esp32c2/include/hal/i2c_ll.h b/components/hal/esp32c2/include/hal/i2c_ll.h
index 1d43bce85a..104df947c6 100644
--- a/components/hal/esp32c2/include/hal/i2c_ll.h
+++ b/components/hal/esp32c2/include/hal/i2c_ll.h
@@ -667,18 +667,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
-    hw->scl_sp_conf.scl_rst_slv_en = 1;
+    hw->scl_sp_conf.scl_rst_slv_en = enable;
     hw->ctr.conf_upgate = 1;
     // hardware will clear scl_rst_slv_en after sending SCL pulses,
-    // and we should set conf_upgate bit to synchronize register value.
-    while (hw->scl_sp_conf.scl_rst_slv_en);
-    hw->ctr.conf_upgate = 1;
+    // and we should set conf_upgate bit to synchronize register value after this function.
+}
+
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return hw->scl_sp_conf.scl_rst_slv_en;
 }
 
 /**
diff --git a/components/hal/esp32c3/include/hal/i2c_ll.h b/components/hal/esp32c3/include/hal/i2c_ll.h
index 4c5faed2c4..c74f591c01 100644
--- a/components/hal/esp32c3/include/hal/i2c_ll.h
+++ b/components/hal/esp32c3/include/hal/i2c_ll.h
@@ -790,18 +790,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
-    hw->scl_sp_conf.scl_rst_slv_en = 1;
+    hw->scl_sp_conf.scl_rst_slv_en = enable;
     hw->ctr.conf_upgate = 1;
     // hardware will clear scl_rst_slv_en after sending SCL pulses,
-    // and we should set conf_upgate bit to synchronize register value.
-    while (hw->scl_sp_conf.scl_rst_slv_en);
-    hw->ctr.conf_upgate = 1;
+    // and we should set conf_upgate bit to synchronize register value after this function.
+}
+
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return hw->scl_sp_conf.scl_rst_slv_en;
 }
 
 /**
diff --git a/components/hal/esp32c5/include/hal/i2c_ll.h b/components/hal/esp32c5/include/hal/i2c_ll.h
index fbb4022f6d..aba9ef9f1d 100644
--- a/components/hal/esp32c5/include/hal/i2c_ll.h
+++ b/components/hal/esp32c5/include/hal/i2c_ll.h
@@ -738,18 +738,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
-    hw->scl_sp_conf.scl_rst_slv_en = 1;
+    hw->scl_sp_conf.scl_rst_slv_en = enable;
     hw->ctr.conf_upgate = 1;
     // hardware will clear scl_rst_slv_en after sending SCL pulses,
-    // and we should set conf_upgate bit to synchronize register value.
-    while (hw->scl_sp_conf.scl_rst_slv_en);
-    hw->ctr.conf_upgate = 1;
+    // and we should set conf_upgate bit to synchronize register value after this function.
+}
+
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return hw->scl_sp_conf.scl_rst_slv_en;
 }
 
 /**
diff --git a/components/hal/esp32c6/include/hal/i2c_ll.h b/components/hal/esp32c6/include/hal/i2c_ll.h
index 3bd42d6038..2f16fe9eb5 100644
--- a/components/hal/esp32c6/include/hal/i2c_ll.h
+++ b/components/hal/esp32c6/include/hal/i2c_ll.h
@@ -754,18 +754,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
-    hw->scl_sp_conf.scl_rst_slv_en = 1;
+    hw->scl_sp_conf.scl_rst_slv_en = enable;
     hw->ctr.conf_upgate = 1;
     // hardware will clear scl_rst_slv_en after sending SCL pulses,
-    // and we should set conf_upgate bit to synchronize register value.
-    while (hw->scl_sp_conf.scl_rst_slv_en);
-    hw->ctr.conf_upgate = 1;
+    // and we should set conf_upgate bit to synchronize register value after this function.
+}
+
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return hw->scl_sp_conf.scl_rst_slv_en;
 }
 
 /**
diff --git a/components/hal/esp32h2/include/hal/i2c_ll.h b/components/hal/esp32h2/include/hal/i2c_ll.h
index 8e9870c944..255a2696d1 100644
--- a/components/hal/esp32h2/include/hal/i2c_ll.h
+++ b/components/hal/esp32h2/include/hal/i2c_ll.h
@@ -740,18 +740,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
-    hw->scl_sp_conf.scl_rst_slv_en = 1;
+    hw->scl_sp_conf.scl_rst_slv_en = enable;
     hw->ctr.conf_upgate = 1;
     // hardware will clear scl_rst_slv_en after sending SCL pulses,
-    // and we should set conf_upgate bit to synchronize register value.
-    while (hw->scl_sp_conf.scl_rst_slv_en);
-    hw->ctr.conf_upgate = 1;
+    // and we should set conf_upgate bit to synchronize register value after this function.
+}
+
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return hw->scl_sp_conf.scl_rst_slv_en;
 }
 
 /**
diff --git a/components/hal/esp32p4/include/hal/i2c_ll.h b/components/hal/esp32p4/include/hal/i2c_ll.h
index 9693707256..2f6ebbd0bb 100644
--- a/components/hal/esp32p4/include/hal/i2c_ll.h
+++ b/components/hal/esp32p4/include/hal/i2c_ll.h
@@ -742,18 +742,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
-    hw->scl_sp_conf.scl_rst_slv_en = 1;
+    hw->scl_sp_conf.scl_rst_slv_en = enable;
     hw->ctr.conf_upgate = 1;
     // hardware will clear scl_rst_slv_en after sending SCL pulses,
-    // and we should set conf_upgate bit to synchronize register value.
-    while (hw->scl_sp_conf.scl_rst_slv_en);
-    hw->ctr.conf_upgate = 1;
+    // and we should set conf_upgate bit to synchronize register value after this function.
+}
+
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return hw->scl_sp_conf.scl_rst_slv_en;
 }
 
 /**
diff --git a/components/hal/esp32s2/include/hal/i2c_ll.h b/components/hal/esp32s2/include/hal/i2c_ll.h
index 1061180e39..4ce9e3c550 100644
--- a/components/hal/esp32s2/include/hal/i2c_ll.h
+++ b/components/hal/esp32s2/include/hal/i2c_ll.h
@@ -573,7 +573,7 @@ static inline void i2c_ll_get_stop_timing(i2c_dev_t *hw, int *setup_time, int *h
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  ptr Pointer to data buffer
- * @param  len Amount of data needs to be writen
+ * @param  len Amount of data needs to be written
  *
  * @return None.
  */
@@ -658,16 +658,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
     hw->scl_sp_conf.scl_rst_slv_en = 0;
     hw->scl_sp_conf.scl_rst_slv_en = 1;
 }
 
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return true; // not supported on esp32s2
+}
+
 /**
  * @brief Set I2C source clock
  *
@@ -717,7 +730,7 @@ static inline void i2c_ll_master_init(i2c_dev_t *hw)
  *         Otherwise it is not needed.
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  internal_od_ena Set true to enble internal open-drain, otherwise, set it false.
+ * @param  internal_od_ena Set true to enable internal open-drain, otherwise, set it false.
  *
  * @return None
  */
@@ -908,7 +921,7 @@ typedef enum {
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  high_period The I2C SCL hight period (in core clock cycle, hight_period > 2)
+ * @param  high_period The I2C SCL high period (in core clock cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in core clock cycle, low_period > 1)
  * @param  wait_high_period The I2C SCL wait rising edge period.
  *
@@ -1096,7 +1109,7 @@ static inline void i2c_ll_slave_disable_rx_it(i2c_dev_t *hw)
  * @brief  Configure I2C SCL timing
  *
  * @param  hw Beginning address of the peripheral registers
- * @param  hight_period The I2C SCL hight period (in APB cycle, hight_period > 2)
+ * @param  hight_period The I2C SCL high period (in APB cycle, hight_period > 2)
  * @param  low_period The I2C SCL low period (in APB cycle, low_period > 1)
  *
  * @return None.
diff --git a/components/hal/esp32s3/include/hal/i2c_ll.h b/components/hal/esp32s3/include/hal/i2c_ll.h
index caf58b9022..3a20726553 100644
--- a/components/hal/esp32s3/include/hal/i2c_ll.h
+++ b/components/hal/esp32s3/include/hal/i2c_ll.h
@@ -797,16 +797,29 @@ static inline void i2c_ll_master_fsm_rst(i2c_dev_t *hw)
  *
  * @param  hw Beginning address of the peripheral registers
  * @param  slave_pulses When I2C master is IDLE, the number of pulses will be sent out.
+ * @param  enable True to start the state machine, otherwise, false
  *
  * @return None
  */
-static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses)
+static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, bool enable)
 {
     hw->scl_sp_conf.scl_rst_slv_num = slave_pulses;
     hw->scl_sp_conf.scl_rst_slv_en = 1;
     hw->ctr.conf_upgate = 1;
 }
 
+/**
+ * @brief Get the clear bus state
+ *
+ * @param hw Beginning address of the peripheral registers
+ *
+ * @return true: the clear bus not finish, otherwise, false.
+ */
+static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
+{
+    return true; // not supported on esp32s3
+}
+
 /**
  * @brief Set I2C source clock
  *

From 7be31411958ce83437ee83ec4d4f72508325e165 Mon Sep 17 00:00:00 2001
From: "C.S.M" <caosenmiao@espressif.com>
Date: Wed, 4 Sep 2024 14:02:31 +0800
Subject: [PATCH 3/4] fix(i2c): Fix the i2c sda/scl force out register value on
 some esp chips

---
 components/hal/esp32c5/include/hal/i2c_ll.h | 8 ++++----
 components/hal/esp32c6/include/hal/i2c_ll.h | 8 ++++----
 components/hal/esp32h2/include/hal/i2c_ll.h | 8 ++++----
 components/hal/esp32p4/include/hal/i2c_ll.h | 8 ++++----
 4 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/components/hal/esp32c5/include/hal/i2c_ll.h b/components/hal/esp32c5/include/hal/i2c_ll.h
index aba9ef9f1d..2bb6dd327e 100644
--- a/components/hal/esp32c5/include/hal/i2c_ll.h
+++ b/components/hal/esp32c5/include/hal/i2c_ll.h
@@ -801,8 +801,8 @@ static inline void i2c_ll_master_init(i2c_dev_t *hw)
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
     ctrl_reg.ms_mode = 1;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
 }
 
@@ -817,8 +817,8 @@ static inline void i2c_ll_slave_init(i2c_dev_t *hw)
 {
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
     hw->fifo_conf.fifo_addr_cfg_en = 0;
 }
diff --git a/components/hal/esp32c6/include/hal/i2c_ll.h b/components/hal/esp32c6/include/hal/i2c_ll.h
index 2f16fe9eb5..e8aaa77828 100644
--- a/components/hal/esp32c6/include/hal/i2c_ll.h
+++ b/components/hal/esp32c6/include/hal/i2c_ll.h
@@ -896,8 +896,8 @@ static inline void i2c_ll_master_init(i2c_dev_t *hw)
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
     ctrl_reg.ms_mode = 1;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
 }
 
@@ -912,8 +912,8 @@ static inline void i2c_ll_slave_init(i2c_dev_t *hw)
 {
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
     hw->fifo_conf.fifo_addr_cfg_en = 0;
 }
diff --git a/components/hal/esp32h2/include/hal/i2c_ll.h b/components/hal/esp32h2/include/hal/i2c_ll.h
index 255a2696d1..d636cc0c71 100644
--- a/components/hal/esp32h2/include/hal/i2c_ll.h
+++ b/components/hal/esp32h2/include/hal/i2c_ll.h
@@ -803,8 +803,8 @@ static inline void i2c_ll_master_init(i2c_dev_t *hw)
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
     ctrl_reg.ms_mode = 1;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
 }
 
@@ -819,8 +819,8 @@ static inline void i2c_ll_slave_init(i2c_dev_t *hw)
 {
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
     hw->fifo_conf.fifo_addr_cfg_en = 0;
 }
diff --git a/components/hal/esp32p4/include/hal/i2c_ll.h b/components/hal/esp32p4/include/hal/i2c_ll.h
index 2f6ebbd0bb..7471583274 100644
--- a/components/hal/esp32p4/include/hal/i2c_ll.h
+++ b/components/hal/esp32p4/include/hal/i2c_ll.h
@@ -900,8 +900,8 @@ static inline void i2c_ll_master_init(i2c_dev_t *hw)
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
     ctrl_reg.ms_mode = 1;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
 }
 
@@ -916,8 +916,8 @@ static inline void i2c_ll_slave_init(i2c_dev_t *hw)
 {
     typeof(hw->ctr) ctrl_reg;
     ctrl_reg.val = 0;
-    ctrl_reg.sda_force_out = 1;
-    ctrl_reg.scl_force_out = 1;
+    ctrl_reg.sda_force_out = 0;
+    ctrl_reg.scl_force_out = 0;
     hw->ctr.val = ctrl_reg.val;
     hw->fifo_conf.fifo_addr_cfg_en = 0;
 }

From 403bd86a213fb40158d6df65ccc69ddbbcd838f3 Mon Sep 17 00:00:00 2001
From: "C.S.M" <caosenmiao@espressif.com>
Date: Mon, 9 Sep 2024 19:15:02 +0800
Subject: [PATCH 4/4] fix(i2c): Fix the wrong return value of
 esp32,esp32s2,esp32s3

---
 components/hal/esp32/include/hal/i2c_ll.h   | 2 +-
 components/hal/esp32s2/include/hal/i2c_ll.h | 2 +-
 components/hal/esp32s3/include/hal/i2c_ll.h | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/components/hal/esp32/include/hal/i2c_ll.h b/components/hal/esp32/include/hal/i2c_ll.h
index dc6a4be60d..7e5d352337 100644
--- a/components/hal/esp32/include/hal/i2c_ll.h
+++ b/components/hal/esp32/include/hal/i2c_ll.h
@@ -647,7 +647,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, b
  */
 static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
 {
-    return true;
+    return false;
 }
 
 /**
diff --git a/components/hal/esp32s2/include/hal/i2c_ll.h b/components/hal/esp32s2/include/hal/i2c_ll.h
index 4ce9e3c550..9391b32b27 100644
--- a/components/hal/esp32s2/include/hal/i2c_ll.h
+++ b/components/hal/esp32s2/include/hal/i2c_ll.h
@@ -678,7 +678,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, b
  */
 static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
 {
-    return true; // not supported on esp32s2
+    return false; // not supported on esp32s2
 }
 
 /**
diff --git a/components/hal/esp32s3/include/hal/i2c_ll.h b/components/hal/esp32s3/include/hal/i2c_ll.h
index 3a20726553..50dfb6eaf7 100644
--- a/components/hal/esp32s3/include/hal/i2c_ll.h
+++ b/components/hal/esp32s3/include/hal/i2c_ll.h
@@ -817,7 +817,7 @@ static inline void i2c_ll_master_clr_bus(i2c_dev_t *hw, uint32_t slave_pulses, b
  */
 static inline bool i2c_ll_master_is_bus_clear_done(i2c_dev_t *hw)
 {
-    return true; // not supported on esp32s3
+    return false; // not supported on esp32s3
 }
 
 /**