docs(i2c): Modify some variables in I2C driver for good docs

components/driver/i2c/i2c_master.c

@@ -933,13 +933,13 @@ esp_err_t i2c_del_master_bus(i2c_master_bus_handle_t bus_handle)
     return ESP_OK;
 }
 
-esp_err_t i2c_master_bus_reset(i2c_master_bus_handle_t handle)
+esp_err_t i2c_master_bus_reset(i2c_master_bus_handle_t bus_handle)
 {
-    ESP_RETURN_ON_FALSE((handle != NULL), ESP_ERR_INVALID_ARG, TAG, "This bus is not initialized");
+    ESP_RETURN_ON_FALSE((bus_handle != NULL), ESP_ERR_INVALID_ARG, TAG, "This bus is not initialized");
     // Reset I2C master bus
-    ESP_RETURN_ON_ERROR(s_i2c_hw_fsm_reset(handle), TAG, "I2C master bus reset failed");
+    ESP_RETURN_ON_ERROR(s_i2c_hw_fsm_reset(bus_handle), TAG, "I2C master bus reset failed");
     // Reset I2C status state
-    atomic_store(&handle->status, I2C_STATUS_IDLE);
+    atomic_store(&bus_handle->status, I2C_STATUS_IDLE);
     return ESP_OK;
 }
 
@@ -1022,24 +1022,24 @@ esp_err_t i2c_master_receive(i2c_master_dev_handle_t i2c_dev, uint8_t *read_buff
     return ESP_OK;
 }
 
-esp_err_t i2c_master_probe(i2c_master_bus_handle_t i2c_master, uint16_t address, int xfer_timeout_ms)
+esp_err_t i2c_master_probe(i2c_master_bus_handle_t bus_handle, uint16_t address, int xfer_timeout_ms)
 {
-    ESP_RETURN_ON_FALSE(i2c_master != NULL, ESP_ERR_INVALID_ARG, TAG, "i2c handle not initialized");
+    ESP_RETURN_ON_FALSE(bus_handle != NULL, ESP_ERR_INVALID_ARG, TAG, "i2c handle not initialized");
     TickType_t ticks_to_wait = (xfer_timeout_ms == -1) ? portMAX_DELAY : pdMS_TO_TICKS(xfer_timeout_ms);
-    if (xSemaphoreTake(i2c_master->bus_lock_mux, ticks_to_wait) != pdTRUE) {
+    if (xSemaphoreTake(bus_handle->bus_lock_mux, ticks_to_wait) != pdTRUE) {
         return ESP_ERR_TIMEOUT;
     }
 
-    i2c_master->cmd_idx = 0;
-    i2c_master->trans_idx = 0;
-    i2c_master->trans_done = false;
-    i2c_hal_context_t *hal = &i2c_master->base->hal;
+    bus_handle->cmd_idx = 0;
+    bus_handle->trans_idx = 0;
+    bus_handle->trans_done = false;
+    i2c_hal_context_t *hal = &bus_handle->base->hal;
     i2c_operation_t i2c_ops[] = {
         {.hw_cmd = I2C_TRANS_START_COMMAND},
         {.hw_cmd = I2C_TRANS_STOP_COMMAND},
     };
 
-    i2c_master->i2c_trans = (i2c_transaction_t) {
+    bus_handle->i2c_trans = (i2c_transaction_t) {
         .device_address = address,
         .ops = i2c_ops,
         .cmd_count = DIM(i2c_ops),
@@ -1048,20 +1048,20 @@ esp_err_t i2c_master_probe(i2c_master_bus_handle_t i2c_master, uint16_t address,
     // I2C probe does not have i2c device module. So set the clock parameter independently
     // This will not influence device transaction.
     I2C_CLOCK_SRC_ATOMIC() {
-        i2c_ll_set_source_clk(hal->dev, i2c_master->base->clk_src);
-        i2c_hal_set_bus_timing(hal, 100000, i2c_master->base->clk_src, i2c_master->base->clk_src_freq_hz);
+        i2c_ll_set_source_clk(hal->dev, bus_handle->base->clk_src);
+        i2c_hal_set_bus_timing(hal, 100000, bus_handle->base->clk_src, bus_handle->base->clk_src_freq_hz);
     }
     i2c_ll_master_set_fractional_divider(hal->dev, 0, 0);
     i2c_ll_update(hal->dev);
 
-    s_i2c_send_commands(i2c_master, ticks_to_wait);
-    if (i2c_master->status == I2C_STATUS_ACK_ERROR) {
+    s_i2c_send_commands(bus_handle, ticks_to_wait);
+    if (bus_handle->status == I2C_STATUS_ACK_ERROR) {
         // Reset the status to done, in order not influence next time transaction.
-        i2c_master->status = I2C_STATUS_DONE;
-        xSemaphoreGive(i2c_master->bus_lock_mux);
+        bus_handle->status = I2C_STATUS_DONE;
+        xSemaphoreGive(bus_handle->bus_lock_mux);
         return ESP_ERR_NOT_FOUND;
     }
-    xSemaphoreGive(i2c_master->bus_lock_mux);
+    xSemaphoreGive(bus_handle->bus_lock_mux);
     return ESP_OK;
 }
 
@@ -1088,19 +1088,19 @@ esp_err_t i2c_master_register_event_callbacks(i2c_master_dev_handle_t i2c_dev, c
     return ESP_OK;
 }
 
-esp_err_t i2c_master_wait_all_done(i2c_master_bus_handle_t i2c_master, int timeout_ms)
+esp_err_t i2c_master_bus_wait_all_done(i2c_master_bus_handle_t bus_handle, int timeout_ms)
 {
-    ESP_RETURN_ON_FALSE(i2c_master, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
+    ESP_RETURN_ON_FALSE(bus_handle, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
     TickType_t wait_ticks = timeout_ms < 0 ? portMAX_DELAY : pdMS_TO_TICKS(timeout_ms);
     i2c_transaction_t t;
 
-    size_t cnt = i2c_master->num_trans_inflight;
+    size_t cnt = bus_handle->num_trans_inflight;
     for (size_t i = 0; i < cnt; i++) {
-        ESP_RETURN_ON_FALSE(xQueueReceive(i2c_master->trans_queues[I2C_TRANS_QUEUE_COMPLETE], &t, wait_ticks) == pdTRUE,
+        ESP_RETURN_ON_FALSE(xQueueReceive(bus_handle->trans_queues[I2C_TRANS_QUEUE_COMPLETE], &t, wait_ticks) == pdTRUE,
                             ESP_ERR_TIMEOUT, TAG, "flush timeout");
-        ESP_RETURN_ON_FALSE(xQueueSend(i2c_master->trans_queues[I2C_TRANS_QUEUE_READY], &t, 0) == pdTRUE,
+        ESP_RETURN_ON_FALSE(xQueueSend(bus_handle->trans_queues[I2C_TRANS_QUEUE_READY], &t, 0) == pdTRUE,
                             ESP_ERR_INVALID_STATE, TAG, "ready queue full");
-        i2c_master->num_trans_inflight--;
+        bus_handle->num_trans_inflight--;
     }
     return ESP_OK;
 

components/driver/i2c/include/driver/i2c_master.h

@@ -28,7 +28,7 @@ typedef struct {
     size_t trans_queue_depth;             /*!< Depth of internal transfer queue, increase this value can support more transfers pending in the background, only valid in asynchronous transaction. (Typically max_device_num * per_transaction)*/
     struct {
         uint32_t enable_internal_pullup:1;   /*!< Enable internal pullups. Note: This is not strong enough to pullup buses under high-speed frequency. Recommend proper external pull-up if possible */
-    } flags;
+    } flags;                              /*!< I2C master config flags */
 } i2c_master_bus_config_t;
 
 /**
@@ -157,13 +157,15 @@ esp_err_t i2c_master_receive(i2c_master_dev_handle_t i2c_dev, uint8_t *read_buff
 /**
  * @brief Probe I2C address, if address is correct and ACK is received, this function will return ESP_OK.
  *
- * @param[in] i2c_dev I2C master device handle that created by `i2c_master_bus_add_device`.
+ * @param[in] bus_handle I2C master device handle that created by `i2c_master_bus_add_device`.
+ * @param[in] address I2C device address that you want to probe.
  * @param[in] xfer_timeout_ms Wait timeout, in ms. Note: -1 means wait forever (Not recommended in this function).
  * @return
  *      - ESP_OK: I2C device probe successfully
+ *      - ESP_ERR_NOT_FOUND: I2C probe failed, doesn't find the device with specific address you gave.
  *      - ESP_ERR_TIMEOUT: Operation timeout(larger than xfer_timeout_ms) because the bus is busy or hardware crash.
  */
-esp_err_t i2c_master_probe(i2c_master_bus_handle_t i2c_master, uint16_t address, int xfer_timeout_ms);
+esp_err_t i2c_master_probe(i2c_master_bus_handle_t bus_handle, uint16_t address, int xfer_timeout_ms);
 
 /**
  * @brief Register I2C transaction callbacks for a master device
@@ -186,18 +188,18 @@ esp_err_t i2c_master_register_event_callbacks(i2c_master_dev_handle_t i2c_dev, c
 /**
  * @brief Reset the I2C master bus.
  *
- * @param handle I2C bus handle.
+ * @param bus_handle I2C bus handle.
  * @return
  *      - ESP_OK: Reset succeed.
  *      - ESP_ERR_INVALID_ARG: I2C master bus handle is not initialized.
  *      - Otherwise: Reset failed.
  */
-esp_err_t i2c_master_bus_reset(i2c_master_bus_handle_t handle);
+esp_err_t i2c_master_bus_reset(i2c_master_bus_handle_t bus_handle);
 
 /**
  * @brief Wait for all pending I2C transactions done
  *
- * @param[in] i2c_master I2C bus handle
+ * @param[in] bus_handle I2C bus handle
  * @param[in] timeout_ms Wait timeout, in ms. Specially, -1 means to wait forever.
  * @return
  *      - ESP_OK: Flush transactions successfully
@@ -205,7 +207,7 @@ esp_err_t i2c_master_bus_reset(i2c_master_bus_handle_t handle);
  *      - ESP_ERR_TIMEOUT: Flush transactions failed because of timeout
  *      - ESP_FAIL: Flush transactions failed because of other error
  */
-esp_err_t i2c_master_wait_all_done(i2c_master_bus_handle_t i2c_master, int timeout_ms);
+esp_err_t i2c_master_bus_wait_all_done(i2c_master_bus_handle_t bus_handle, int timeout_ms);
 
 #ifdef __cplusplus
 }

components/driver/i2c/include/driver/i2c_slave.h

@@ -40,7 +40,7 @@ typedef struct {
 #if SOC_I2C_SLAVE_SUPPORT_SLAVE_UNMATCH
         uint32_t slave_unmatch_en:1;         /*!< Can trigger unmatch interrupt when slave address does not match what master sends*/
 #endif
-    } flags;
+    } flags;                                 /*!< I2C slave config flags */
 } i2c_slave_config_t;
 
 /**

components/driver/i2c/include/driver/i2c_types.h

@@ -78,7 +78,7 @@ typedef bool (*i2c_master_callback_t)(i2c_master_dev_handle_t i2c_dev, const i2c
  * @brief Event structure used in I2C slave
  */
 typedef struct {
-    uint8_t *buffer;
+    uint8_t *buffer;  /**< Pointer for buffer received in callback. */
 } i2c_slave_rx_done_event_data_t;
 
 /**
@@ -98,7 +98,7 @@ typedef bool (*i2c_slave_received_callback_t)(i2c_slave_dev_handle_t i2c_slave,
  * @brief Stretch cause event structure used in I2C slave
  */
 typedef struct {
-    i2c_slave_stretch_cause_t stretch_cause;
+    i2c_slave_stretch_cause_t stretch_cause;  /*!< Stretch cause can be got in callback */
 } i2c_slave_stretch_event_data_t;
 
 /**

examples/peripherals/i2c/i2c_eeprom/main/i2c_eeprom_main.c

@@ -37,6 +37,7 @@ void app_main(void)
         .i2c_port = PORT_NUMBER,
         .scl_io_num = SCL_IO_PIN,
         .sda_io_num = SDA_IO_PIN,
+        .glitch_ignore_cnt = 7,
     };
     i2c_master_bus_handle_t bus_handle;