feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

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

Browse Source
This commit is contained in:
Cao Sen Miao
2023-11-07 18:42:08 +08:00
parent 614aed7409
commit 9d3d9d16f0
5 changed files with 37 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
components/driver/i2c/i2c_master.c
View File

@ -930,13 +930,13 @@ esp_err_t i2c_del_master_bus(i2c_master_bus_handle_t bus_handle)
return ESP_OK; 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 // 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 // Reset I2C status state
atomic_store(&handle->status, I2C_STATUS_IDLE); atomic_store(&bus_handle->status, I2C_STATUS_IDLE);
return ESP_OK; return ESP_OK;
} }
@ -1019,24 +1019,24 @@ esp_err_t i2c_master_receive(i2c_master_dev_handle_t i2c_dev, uint8_t *read_buff
return ESP_OK; 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); 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; return ESP_ERR_TIMEOUT;
} }
i2c_master->cmd_idx = 0; bus_handle->cmd_idx = 0;
i2c_master->trans_idx = 0; bus_handle->trans_idx = 0;
i2c_master->trans_done = false; bus_handle->trans_done = false;
i2c_hal_context_t *hal = &i2c_master->base->hal; i2c_hal_context_t *hal = &bus_handle->base->hal;
i2c_operation_t i2c_ops[] = { i2c_operation_t i2c_ops[] = {
{.hw_cmd = I2C_TRANS_START_COMMAND}, {.hw_cmd = I2C_TRANS_START_COMMAND},
{.hw_cmd = I2C_TRANS_STOP_COMMAND}, {.hw_cmd = I2C_TRANS_STOP_COMMAND},
}; };
i2c_master->i2c_trans = (i2c_transaction_t) { bus_handle->i2c_trans = (i2c_transaction_t) {
.device_address = address, .device_address = address,
.ops = i2c_ops, .ops = i2c_ops,
.cmd_count = DIM(i2c_ops), .cmd_count = DIM(i2c_ops),
@ -1044,18 +1044,18 @@ 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 // I2C probe does not have i2c device module. So set the clock parameter independently
// This will not influence device transaction. // This will not influence device transaction.
i2c_hal_set_bus_timing(hal, 100000, i2c_master->base->clk_src, i2c_master->base->clk_src_freq_hz); 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_master_set_fractional_divider(hal->dev, 0, 0);
i2c_ll_update(hal->dev); i2c_ll_update(hal->dev);
s_i2c_send_commands(i2c_master, ticks_to_wait); s_i2c_send_commands(bus_handle, ticks_to_wait);
if (i2c_master->status == I2C_STATUS_ACK_ERROR) { if (bus_handle->status == I2C_STATUS_ACK_ERROR) {
// Reset the status to done, in order not influence next time transaction. // Reset the status to done, in order not influence next time transaction.
i2c_master->status = I2C_STATUS_DONE; bus_handle->status = I2C_STATUS_DONE;
xSemaphoreGive(i2c_master->bus_lock_mux); xSemaphoreGive(bus_handle->bus_lock_mux);
return ESP_ERR_NOT_FOUND; return ESP_ERR_NOT_FOUND;
} }
xSemaphoreGive(i2c_master->bus_lock_mux); xSemaphoreGive(bus_handle->bus_lock_mux);
return ESP_OK; return ESP_OK;
} }
@ -1082,19 +1082,19 @@ esp_err_t i2c_master_register_event_callbacks(i2c_master_dev_handle_t i2c_dev, c
return ESP_OK; 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); TickType_t wait_ticks = timeout_ms < 0 ? portMAX_DELAY : pdMS_TO_TICKS(timeout_ms);
i2c_transaction_t t; 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++) { 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_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"); ESP_ERR_INVALID_STATE, TAG, "ready queue full");
i2c_master->num_trans_inflight--; bus_handle->num_trans_inflight--;
} }
return ESP_OK; return ESP_OK;

16
components/driver/i2c/include/driver/i2c_master.h
View File

@ -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)*/ 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 { 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 */ 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; } 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. * @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). * @param[in] xfer_timeout_ms Wait timeout, in ms. Note: -1 means wait forever (Not recommended in this function).
* @return * @return
* - ESP_OK: I2C device probe successfully * - 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_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 * @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. * @brief Reset the I2C master bus.
* *
* @param handle I2C bus handle. * @param bus_handle I2C bus handle.
* @return * @return
* - ESP_OK: Reset succeed. * - ESP_OK: Reset succeed.
* - ESP_ERR_INVALID_ARG: I2C master bus handle is not initialized. * - ESP_ERR_INVALID_ARG: I2C master bus handle is not initialized.
* - Otherwise: Reset failed. * - 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 * @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. * @param[in] timeout_ms Wait timeout, in ms. Specially, -1 means to wait forever.
* @return * @return
* - ESP_OK: Flush transactions successfully * - 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_ERR_TIMEOUT: Flush transactions failed because of timeout
* - ESP_FAIL: Flush transactions failed because of other error * - 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 #ifdef __cplusplus
} }

2
components/driver/i2c/include/driver/i2c_slave.h
View File

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

4
components/driver/i2c/include/driver/i2c_types.h
View File

@ -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 * @brief Event structure used in I2C slave
*/ */
typedef struct { typedef struct {
uint8_t *buffer; uint8_t *buffer; /**< Pointer for buffer received in callback. */
} i2c_slave_rx_done_event_data_t; } 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 * @brief Stretch cause event structure used in I2C slave
*/ */
typedef struct { 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; } i2c_slave_stretch_event_data_t;
/** /**

1
examples/peripherals/i2c/i2c_eeprom/main/i2c_eeprom_main.c
View File

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