Merge branch 'docs/i2c_ng_docs' into 'master'

docs(I2C): Add new programming guide for new I2C driver

See merge request espressif/esp-idf!26752

Author: mythbuster5

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,26 +188,26 @@ 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
  *      - ESP_ERR_INVALID_ARG: Flush transactions failed because of invalid argument
  *      - 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;
 
 /**

docs/_static/diagrams/i2c/i2c_code_structure.png

@@ -0,0 +1,26 @@
+{
+    "head": {
+        "text": "Standard I2C Transaction Timing Diagram"
+    },
+    "signal": [
+    {
+        "node":"A.....B...................C..D.E...............F...G",
+        "period": 0.5},
+    {
+        "name": "SDA",
+        "wave": "1.0...3...3.|.3...4...5...1..0.6...6.|.6...7...10..1", "data": "A6 . A0 R/W ACK D7 . D0 ACK",
+        "period": 0.5},
+    {
+        "name": "SCL",
+        "wave": "1...0..1.0.1|0.1.0.1.0.1.0......1.0.1|0.1.0.1.0..1..",
+        "period": 0.5}
+    ],
+    "config":
+    {
+        "skin": "narrow"
+    },
+    "edge": [
+        "B<->C Write address",
+        "E<->F Write data"
+    ]
+}

docs/_static/diagrams/i2c/i2c_master_module.png

@@ -79,7 +79,9 @@ INPUT = \
     $(PROJECT_PATH)/components/driver/dac/include/driver/dac_cosine.h \
     $(PROJECT_PATH)/components/driver/dac/include/driver/dac_oneshot.h \
     $(PROJECT_PATH)/components/driver/dac/include/driver/dac_types.h \
-    $(PROJECT_PATH)/components/driver/i2c/include/driver/i2c.h \
+    $(PROJECT_PATH)/components/driver/i2c/include/driver/i2c_master.h \
+    $(PROJECT_PATH)/components/driver/i2c/include/driver/i2c_slave.h \
+    $(PROJECT_PATH)/components/driver/i2c/include/driver/i2c_types.h \
     $(PROJECT_PATH)/components/driver/i2s/include/driver/i2s_common.h \
     $(PROJECT_PATH)/components/driver/i2s/include/driver/i2s_pdm.h \
     $(PROJECT_PATH)/components/driver/i2s/include/driver/i2s_std.h \