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

Merge branch 'refactor/remove_i2c_slave_v1' into 'master'

Browse Source 
refactor(i2c): Remove i2c slave v1 driver

See merge request espressif/esp-idf!39329
This commit is contained in:
C.S.M
2025-05-27 15:28:43 +08:00
parent b3560860dd 1f37a8da9a
commit 456ae964a1
14 changed files with 344 additions and 897 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
components/esp_driver_i2c/CMakeLists.txt
View File

@@ -10,11 +10,7 @@ if(CONFIG_SOC_I2C_SUPPORTED)
"i2c_common.c"
)
if(CONFIG_SOC_I2C_SUPPORT_SLAVE)
if(CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2)
list(APPEND srcs "i2c_slave_v2.c")
else()
list(APPEND srcs "i2c_slave.c")
endif()
list(APPEND srcs "i2c_slave.c")
endif()
endif()

6
components/esp_driver_i2c/Kconfig
View File

@@ -18,12 +18,6 @@ menu "ESP-Driver:I2C Configurations"
note: This cannot be used in the I2C legacy driver.
config I2C_ENABLE_SLAVE_DRIVER_VERSION_2
bool "Enable I2C slave driver version 2"
default n
help
I2C slave version 2 solves some existing known issues. Such as write/read workflow, stretch handling, etc.
config I2C_MASTER_ISR_HANDLER_IN_IRAM
bool "Place I2C master ISR handler into IRAM"
default y

23
components/esp_driver_i2c/i2c_private.h
View File

@@ -193,27 +193,6 @@ typedef struct {
uint32_t rcv_fifo_cnt; // receive fifo count.
} i2c_slave_receive_t;
#if !CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2
struct i2c_slave_dev_t {
i2c_bus_t *base; // bus base class
SemaphoreHandle_t slv_rx_mux; // Mutex for slave rx direction
SemaphoreHandle_t slv_tx_mux; // Mutex for slave tx direction
RingbufHandle_t rx_ring_buf; // Handle for rx ringbuffer
RingbufHandle_t tx_ring_buf; // Handle for tx ringbuffer
uint8_t data_buf[SOC_I2C_FIFO_LEN]; // Data buffer for slave
uint32_t trans_data_length; // Send data length
i2c_slave_event_callbacks_t callbacks; // I2C slave callbacks
void *user_ctx; // Callback user context
i2c_slave_fifo_mode_t fifo_mode; // Slave fifo mode.
QueueHandle_t slv_evt_queue; // Event Queue used in slave nonfifo mode.
i2c_slave_evt_t slave_evt; // Slave event structure.
i2c_slave_receive_t receive_desc; // Slave receive descriptor
uint32_t already_receive_len; // Data length already received in ISR.
};
#else // CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2
struct i2c_slave_dev_t {
i2c_bus_t *base; // bus base class
SemaphoreHandle_t operation_mux; // Mux for i2c slave operation
@@ -226,8 +205,6 @@ struct i2c_slave_dev_t {
i2c_slave_receive_t receive_desc; // slave receive descriptor
};
#endif // CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2
/**
* @brief Acquire I2C bus handle
*

616
components/esp_driver_i2c/i2c_slave.c
View File

@@ -1,29 +1,27 @@
/*
* SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#include <sys/param.h>
#include "esp_types.h"
#include "esp_intr_alloc.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/task.h"
#include "freertos/ringbuf.h"
#include "freertos/queue.h"
#include "hal/i2c_hal.h"
#include "soc/i2c_periph.h"
#include "sdkconfig.h"
#include "soc/soc_caps.h"
#include "esp_attr.h"
#include "esp_rom_gpio.h"
#include "driver/gpio.h"
#include "clk_ctrl_os.h"
#include "esp_private/esp_clk.h"
#include "driver/i2c_slave.h"
#include "hal/gpio_ll.h"
#include "esp_err.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/ringbuf.h"
#include "esp_intr_alloc.h"
#include "hal/i2c_ll.h"
#include "i2c_private.h"
#include "driver/i2c_slave.h"
#include "esp_memory_utils.h"
#include "freertos/idf_additions.h"
#if CONFIG_I2C_ENABLE_DEBUG_LOG
// The local log level must be defined before including esp_log.h
// Set the maximum log level for this source file
@@ -32,150 +30,215 @@
#include "esp_log.h"
#include "esp_check.h"
#define I2C_SLAVE_TIMEOUT_DEFAULT (32000) /* I2C slave timeout value, APB clock cycle number */
#define I2C_FIFO_EMPTY_THRESH_VAL_DEFAULT (SOC_I2C_FIFO_LEN/2)
#define I2C_FIFO_FULL_THRESH_VAL_DEFAULT (SOC_I2C_FIFO_LEN/2)
static const char *TAG = "i2c.slave";
static esp_err_t i2c_slave_bus_destroy(i2c_slave_dev_handle_t i2c_slave);
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
static IRAM_ATTR void s_i2c_handle_clock_stretch(i2c_slave_dev_handle_t i2c_slave)
IRAM_ATTR static bool i2c_slave_read_rx(i2c_slave_dev_t *i2c_slave, uint8_t *data, size_t len, size_t *read_len)
{
i2c_hal_context_t *hal = &i2c_slave->base->hal;
if (i2c_slave->callbacks.on_stretch_occur) {
i2c_slave_stretch_event_data_t evt = { 0 };
i2c_hal_context_t *hal = &i2c_slave->base->hal;
i2c_ll_slave_get_stretch_cause(hal->dev, &evt.stretch_cause);
i2c_slave->callbacks.on_stretch_occur(i2c_slave, &evt, i2c_slave->user_ctx);
}
i2c_ll_slave_clear_stretch(hal->dev);
}
#endif
BaseType_t xTaskWoken = pdFALSE;
size_t read_size = len;
size_t actual_size = 0;
size_t available_size = 0;
size_t get_size = 0;
uint8_t *rx_data = NULL;
static IRAM_ATTR void s_i2c_handle_rx_fifo_wm(i2c_slave_dev_handle_t i2c_slave, i2c_slave_receive_t *t)
{
i2c_hal_context_t *hal = &i2c_slave->base->hal;
uint32_t rx_fifo_cnt;
i2c_ll_get_rxfifo_cnt(hal->dev, &rx_fifo_cnt);
uint32_t fifo_cnt_rd = MIN(t->rcv_fifo_cnt, rx_fifo_cnt);
i2c_ll_read_rxfifo(hal->dev, i2c_slave->data_buf, fifo_cnt_rd);
memcpy(t->buffer + i2c_slave->already_receive_len, i2c_slave->data_buf, fifo_cnt_rd);
i2c_slave->already_receive_len += fifo_cnt_rd;
t->rcv_fifo_cnt -= fifo_cnt_rd;
}
static IRAM_ATTR void s_i2c_handle_complete(i2c_slave_dev_handle_t i2c_slave, i2c_slave_receive_t *t, BaseType_t *do_yield)
{
i2c_hal_context_t *hal = &i2c_slave->base->hal;
uint32_t rx_fifo_cnt;
i2c_ll_get_rxfifo_cnt(hal->dev, &rx_fifo_cnt);
if (rx_fifo_cnt != 0) {
i2c_ll_read_rxfifo(hal->dev, i2c_slave->data_buf, t->rcv_fifo_cnt);
memcpy(t->buffer + i2c_slave->already_receive_len, i2c_slave->data_buf, t->rcv_fifo_cnt);
i2c_slave->already_receive_len += t->rcv_fifo_cnt;
t->rcv_fifo_cnt -= t->rcv_fifo_cnt;
vRingbufferGetInfo(i2c_slave->rx_ring_buf, NULL, NULL, NULL, NULL, &available_size);
if (available_size < read_size) {
read_size = available_size;
}
if (i2c_slave->callbacks.on_recv_done) {
i2c_slave_rx_done_event_data_t edata = {
.buffer = t->buffer,
};
i2c_slave->callbacks.on_recv_done(i2c_slave, &edata, i2c_slave->user_ctx);
xSemaphoreGiveFromISR(i2c_slave->slv_rx_mux, do_yield);
i2c_ll_disable_intr_mask(hal->dev, I2C_LL_SLAVE_RX_EVENT_INTR);
}
}
static IRAM_ATTR void s_i2c_handle_tx_fifo_wm(i2c_slave_dev_handle_t i2c_slave, BaseType_t *do_yield)
{
i2c_hal_context_t *hal = &i2c_slave->base->hal;
uint32_t tx_fifo_rem;
i2c_ll_get_txfifo_len(hal->dev, &tx_fifo_rem);
size_t size = 0;
uint8_t *data = (uint8_t *) xRingbufferReceiveUpToFromISR(i2c_slave->tx_ring_buf, &size, tx_fifo_rem);
if (data) {
i2c_ll_write_txfifo(hal->dev, data, size);
vRingbufferReturnItemFromISR(i2c_slave->tx_ring_buf, data, do_yield);
}
if (size <= i2c_slave->trans_data_length) {
portENTER_CRITICAL_ISR(&i2c_slave->base->spinlock);
i2c_slave->trans_data_length -= size;
portEXIT_CRITICAL_ISR(&i2c_slave->base->spinlock);
if (i2c_slave->trans_data_length == 0) {
i2c_ll_slave_disable_tx_it(hal->dev);
while (read_size) {
actual_size = 0;
rx_data = (uint8_t *)xRingbufferReceiveUpToFromISR(i2c_slave->rx_ring_buf, &actual_size, read_size);
if (rx_data != NULL && actual_size != 0) {
memcpy(data + get_size, rx_data, actual_size);
vRingbufferReturnItemFromISR(i2c_slave->rx_ring_buf, rx_data, &xTaskWoken);
get_size += actual_size;
read_size -= actual_size;
} else {
break;
}
} else {
ESP_DRAM_LOGE(TAG, "I2C TX BUFFER SIZE ERROR");
}
*read_len = get_size;
return xTaskWoken;
}
static IRAM_ATTR void s_slave_fifo_isr_handler(uint32_t int_mask, void *arg, BaseType_t *do_yield)
IRAM_ATTR static bool i2c_slave_handle_tx_fifo(i2c_slave_dev_t *i2c_slave)
{
i2c_slave_dev_handle_t i2c_slave = (i2c_slave_dev_handle_t) arg;
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
if (int_mask & I2C_INTR_STRETCH) {
s_i2c_handle_clock_stretch(i2c_slave);
}
#endif
i2c_slave_receive_t *t = &i2c_slave->receive_desc;
if (int_mask & I2C_INTR_SLV_RXFIFO_WM) {
s_i2c_handle_rx_fifo_wm(i2c_slave, t);
}
if (int_mask & I2C_INTR_SLV_COMPLETE) {
s_i2c_handle_complete(i2c_slave, t, do_yield);
}
if (int_mask & I2C_INTR_SLV_TXFIFO_WM) {
s_i2c_handle_tx_fifo_wm(i2c_slave, do_yield);
}
}
static IRAM_ATTR void s_slave_nonfifo_isr_handler(uint32_t int_mask, void *arg, BaseType_t *do_yield)
{
i2c_slave_dev_handle_t i2c_slave = (i2c_slave_dev_handle_t) arg;
BaseType_t xTaskWoken = pdFALSE;
i2c_hal_context_t *hal = &i2c_slave->base->hal;
if (int_mask & I2C_INTR_STRETCH) {
i2c_slave->slave_evt.slave_stretch = 1;
uint8_t *data;
uint32_t fifo_len = 0;
xSemaphoreTakeFromISR(i2c_slave->operation_mux, &xTaskWoken);
i2c_ll_get_txfifo_len(hal->dev, &fifo_len);
size_t actual_get_len = 0;
while (fifo_len > 0) {
data = xRingbufferReceiveUpToFromISR(i2c_slave->tx_ring_buf, &actual_get_len, fifo_len);
if (data) {
portENTER_CRITICAL_ISR(&i2c_slave->base->spinlock);
i2c_ll_write_txfifo(hal->dev, data, actual_get_len);
fifo_len -= actual_get_len;
portEXIT_CRITICAL_ISR(&i2c_slave->base->spinlock);
vRingbufferReturnItemFromISR(i2c_slave->tx_ring_buf, data, &xTaskWoken);
} else {
// No data in ringbuffer, so disable the tx interrupt.
i2c_ll_slave_disable_tx_it(hal->dev);
break;
}
}
xSemaphoreGiveFromISR(i2c_slave->operation_mux, &xTaskWoken);
return xTaskWoken;
}
IRAM_ATTR static bool i2c_slave_handle_rx_fifo(i2c_slave_dev_t *i2c_slave, uint32_t len)
{
i2c_hal_context_t *hal = &i2c_slave->base->hal;
uint8_t data[SOC_I2C_FIFO_LEN];
BaseType_t xTaskWoken = pdFALSE;
xSemaphoreTakeFromISR(i2c_slave->operation_mux, &xTaskWoken);
if (len) {
portENTER_CRITICAL_ISR(&i2c_slave->base->spinlock);
i2c_ll_read_rxfifo(hal->dev, data, len);
portEXIT_CRITICAL_ISR(&i2c_slave->base->spinlock);
BaseType_t res = xRingbufferSendFromISR(i2c_slave->rx_ring_buf, (void *)data, len, &xTaskWoken);
if (res == pdTRUE) {
i2c_slave->rx_data_count += len;
}
}
xSemaphoreGiveFromISR(i2c_slave->operation_mux, &xTaskWoken);
return xTaskWoken;
}
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
IRAM_ATTR static bool i2c_slave_handle_stretch_event(i2c_slave_dev_t *i2c_slave, uint32_t rx_fifo_exist_len)
{
i2c_slave_stretch_cause_t cause;
BaseType_t xTaskWoken = pdFALSE;
i2c_hal_context_t *hal = &i2c_slave->base->hal;
i2c_ll_slave_get_stretch_cause(hal->dev, &cause);
if (cause == I2C_SLAVE_STRETCH_CAUSE_ADDRESS_MATCH) {
if (rx_fifo_exist_len) {
xTaskWoken |= i2c_slave_handle_rx_fifo(i2c_slave, rx_fifo_exist_len);
}
if (i2c_slave->rx_data_count) {
uint32_t len = i2c_slave->rx_data_count;
size_t read_len;
xTaskWoken |= i2c_slave_read_rx(i2c_slave, i2c_slave->receive_desc.buffer, len, &read_len);
i2c_slave_rx_done_event_data_t edata = {};
edata.buffer = i2c_slave->receive_desc.buffer;
edata.length = read_len;
if (i2c_slave->receive_callback) {
xTaskWoken |= i2c_slave->receive_callback(i2c_slave, &edata, i2c_slave->user_ctx);
}
i2c_slave->rx_data_count = 0;
}
i2c_slave_request_event_data_t evt_data = {};
if (i2c_slave->request_callback) {
xTaskWoken |= i2c_slave->request_callback(i2c_slave, &evt_data, i2c_slave->user_ctx);
}
//will clear after request callback
} else if (cause == I2C_SLAVE_STRETCH_CAUSE_TX_EMPTY) {
xTaskWoken |= i2c_slave_handle_tx_fifo(i2c_slave);
i2c_ll_slave_clear_stretch(hal->dev);
} else if (cause == I2C_SLAVE_STRETCH_CAUSE_RX_FULL) {
xTaskWoken |= i2c_slave_handle_rx_fifo(i2c_slave, rx_fifo_exist_len);
i2c_ll_slave_clear_stretch(hal->dev);
}
if (int_mask & I2C_INTR_SLV_COMPLETE) {
i2c_slave->slave_evt.trans_complete = 1;
}
xQueueSendFromISR(i2c_slave->slv_evt_queue, &i2c_slave->slave_evt, do_yield);
return xTaskWoken;
}
#endif
static IRAM_ATTR void s_slave_isr_handle_default(void *arg)
IRAM_ATTR static void i2c_slave_isr_handler(void *arg)
{
i2c_slave_dev_handle_t i2c_slave = (i2c_slave_dev_handle_t) arg;
i2c_hal_context_t *hal = &i2c_slave->base->hal;
portBASE_TYPE HPTaskAwoken = pdFALSE;
uint32_t int_mask = 0;
BaseType_t pxHigherPriorityTaskWoken = false;
i2c_slave_dev_t *i2c_slave = (i2c_slave_dev_t *)arg;
i2c_hal_context_t *hal = &i2c_slave->base->hal;
uint32_t int_mask = 0;
i2c_ll_get_intr_mask(hal->dev, &int_mask);
i2c_ll_clear_intr_mask(hal->dev, int_mask);
if (int_mask == 0) {
return;
uint32_t rx_fifo_exist_len = 0;
i2c_ll_get_rxfifo_cnt(hal->dev, &rx_fifo_exist_len);
i2c_slave_read_write_status_t slave_rw = i2c_ll_slave_get_read_write_status(hal->dev);
if (int_mask & I2C_INTR_SLV_RXFIFO_WM) {
pxHigherPriorityTaskWoken |= i2c_slave_handle_rx_fifo(i2c_slave, rx_fifo_exist_len);
}
#if SOC_I2C_SLAVE_SUPPORT_SLAVE_UNMATCH
if (int_mask & I2C_INTR_UNMATCH) {
i2c_slave->slave_evt.addr_unmatch = 1;
ESP_DRAM_LOGE(TAG, "I2C address not match, trans failed");
if (int_mask & I2C_INTR_SLV_COMPLETE) {
if (rx_fifo_exist_len) {
pxHigherPriorityTaskWoken |= i2c_slave_handle_rx_fifo(i2c_slave, rx_fifo_exist_len);
}
if (i2c_slave->rx_data_count) {
uint32_t len = i2c_slave->rx_data_count;
size_t read_len;
pxHigherPriorityTaskWoken |= i2c_slave_read_rx(i2c_slave, i2c_slave->receive_desc.buffer, len, &read_len);
i2c_slave_rx_done_event_data_t edata = {};
edata.buffer = i2c_slave->receive_desc.buffer;
edata.length = read_len;
if (i2c_slave->receive_callback) {
pxHigherPriorityTaskWoken |= i2c_slave->receive_callback(i2c_slave, &edata, i2c_slave->user_ctx);
}
i2c_slave->rx_data_count = 0;
}
if (slave_rw == I2C_SLAVE_READ_BY_MASTER) {
#if !SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
i2c_slave_request_event_data_t evt_data = {};
if (i2c_slave->request_callback) {
pxHigherPriorityTaskWoken |= i2c_slave->request_callback(i2c_slave, &evt_data, i2c_slave->user_ctx);
}
#endif
}
#if CONFIG_IDF_TARGET_ESP32C5
// Workaround for c5 digital bug. Please note that following code has no
// functionality. It's just use for workaround the potential issue for avoiding
// secondary transaction.
i2c_ll_slave_enable_auto_start(hal->dev, true);
i2c_ll_start_trans(hal->dev);
i2c_ll_slave_enable_auto_start(hal->dev, false);
#endif
}
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
if (int_mask & I2C_INTR_STRETCH) { // STRETCH
pxHigherPriorityTaskWoken |= i2c_slave_handle_stretch_event(i2c_slave, rx_fifo_exist_len);
}
#endif
if (i2c_slave->fifo_mode == I2C_SLAVE_NONFIFO) {
s_slave_nonfifo_isr_handler(int_mask, i2c_slave, &HPTaskAwoken);
} else {
s_slave_fifo_isr_handler(int_mask, i2c_slave, &HPTaskAwoken);
if (int_mask & I2C_INTR_SLV_TXFIFO_WM) { // TX FiFo Empty
pxHigherPriorityTaskWoken |= i2c_slave_handle_tx_fifo(i2c_slave);
}
//We only need to check here if there is a high-priority task needs to be switched.
if (HPTaskAwoken == pdTRUE) {
if (pxHigherPriorityTaskWoken) {
portYIELD_FROM_ISR();
}
}
static esp_err_t i2c_slave_device_destroy(i2c_slave_dev_handle_t i2c_slave)
{
esp_err_t ret = ESP_OK;
if (i2c_slave->base) {
i2c_ll_disable_intr_mask(i2c_slave->base->hal.dev, I2C_LL_SLAVE_EVENT_INTR);
i2c_common_deinit_pins(i2c_slave->base);
ret = i2c_release_bus_handle(i2c_slave->base);
}
if (i2c_slave->rx_ring_buf) {
vRingbufferDeleteWithCaps(i2c_slave->rx_ring_buf);
i2c_slave->rx_ring_buf = NULL;
}
if (i2c_slave->tx_ring_buf) {
vRingbufferDeleteWithCaps(i2c_slave->tx_ring_buf);
i2c_slave->tx_ring_buf = NULL;
}
if (i2c_slave->operation_mux) {
vSemaphoreDeleteWithCaps(i2c_slave->operation_mux);
i2c_slave->operation_mux = NULL;
}
if (i2c_slave->receive_desc.buffer) {
free(i2c_slave->receive_desc.buffer);
}
free(i2c_slave);
return ret;
}
esp_err_t i2c_new_slave_device(const i2c_slave_config_t *slave_config, i2c_slave_dev_handle_t *ret_handle)
@@ -191,49 +254,38 @@ esp_err_t i2c_new_slave_device(const i2c_slave_config_t *slave_config, i2c_slave
ESP_RETURN_ON_FALSE(slave_config->i2c_port != (SOC_I2C_NUM - 1), ESP_ERR_NOT_SUPPORTED, TAG, "LP i2c is not supported in I2C slave");
#endif
ESP_RETURN_ON_FALSE(slave_config->i2c_port < SOC_HP_I2C_NUM || slave_config->i2c_port == -1, ESP_ERR_INVALID_ARG, TAG, "invalid i2c port number");
ESP_RETURN_ON_FALSE((slave_config->send_buf_depth > 0), ESP_ERR_INVALID_ARG, TAG, "invalid SCL speed");
#if SOC_I2C_SLAVE_SUPPORT_BROADCAST
ESP_RETURN_ON_FALSE(((slave_config->addr_bit_len != I2C_ADDR_BIT_LEN_10) || (!slave_config->flags.broadcast_en)), ESP_ERR_INVALID_STATE, TAG, "10bits address cannot used together with broadcast");
#endif
int i2c_port_num = slave_config->i2c_port;
i2c_slave = heap_caps_calloc(1, sizeof(i2c_slave_dev_t), I2C_MEM_ALLOC_CAPS);
ESP_RETURN_ON_FALSE(i2c_slave, ESP_ERR_NO_MEM, TAG, "no memory for i2c slave bus");
ESP_GOTO_ON_ERROR(i2c_acquire_bus_handle(i2c_port_num, &i2c_slave->base, I2C_BUS_MODE_SLAVE), err, TAG, "I2C bus acquire failed");
i2c_port_num = i2c_slave->base->port_num;
ESP_GOTO_ON_ERROR(i2c_acquire_bus_handle(slave_config->i2c_port, &i2c_slave->base, I2C_BUS_MODE_SLAVE), err, TAG, "I2C bus acquire failed");
i2c_hal_context_t *hal = &i2c_slave->base->hal;
i2c_slave->base->scl_num = slave_config->scl_io_num;
i2c_slave->base->sda_num = slave_config->sda_io_num;
#if SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
i2c_slave->fifo_mode = (slave_config->flags.access_ram_en == true) ? I2C_SLAVE_NONFIFO : I2C_SLAVE_FIFO;
#endif
#if SOC_I2C_SLAVE_SUPPORT_SLAVE_UNMATCH
if (slave_config->flags.slave_unmatch_en) {
i2c_ll_enable_intr_mask(hal->dev, I2C_SLAVE_ADDR_UNMATCH_INT_ENA_M);
}
#endif
i2c_slave->base->pull_up_enable = slave_config->flags.enable_internal_pullup;
i2c_slave->rx_data_count = 0;
i2c_port_num_t i2c_port_num = i2c_slave->base->port_num;
ESP_GOTO_ON_ERROR(i2c_common_set_pins(i2c_slave->base), err, TAG, "i2c slave set pins failed");
i2c_slave->rx_ring_buf = xRingbufferCreateWithCaps(slave_config->receive_buf_depth, RINGBUF_TYPE_BYTEBUF, I2C_MEM_ALLOC_CAPS);
ESP_GOTO_ON_FALSE(i2c_slave->rx_ring_buf != NULL, ESP_ERR_INVALID_STATE, err, TAG, "ringbuffer create failed");
i2c_slave->operation_mux = xSemaphoreCreateBinaryWithCaps(I2C_MEM_ALLOC_CAPS);
ESP_GOTO_ON_FALSE(i2c_slave->operation_mux, ESP_ERR_NO_MEM, err, TAG, "No memory for binary semaphore");
xSemaphoreGive(i2c_slave->operation_mux);
uint8_t *rcv_buffer = heap_caps_calloc(1, slave_config->receive_buf_depth, I2C_MEM_ALLOC_CAPS);
ESP_RETURN_ON_FALSE(rcv_buffer, ESP_ERR_NO_MEM, TAG, "no memory for i2c slave receive internal buffer");
i2c_slave->receive_desc.buffer = rcv_buffer;
i2c_slave->receive_desc.rcv_fifo_cnt = slave_config->receive_buf_depth;
i2c_slave->tx_ring_buf = xRingbufferCreateWithCaps(slave_config->send_buf_depth, RINGBUF_TYPE_BYTEBUF, I2C_MEM_ALLOC_CAPS);
ESP_GOTO_ON_FALSE(i2c_slave->tx_ring_buf != NULL, ESP_ERR_INVALID_STATE, err, TAG, "ringbuffer create failed");
i2c_slave->slv_rx_mux = xSemaphoreCreateBinaryWithCaps(I2C_MEM_ALLOC_CAPS);
ESP_GOTO_ON_FALSE(i2c_slave->slv_rx_mux, ESP_ERR_NO_MEM, err, TAG, "No memory for binary semaphore");
i2c_slave->slv_tx_mux = xSemaphoreCreateBinaryWithCaps(I2C_MEM_ALLOC_CAPS);
ESP_GOTO_ON_FALSE(i2c_slave->slv_tx_mux, ESP_ERR_NO_MEM, err, TAG, "No memory for binary semaphore");
i2c_slave->slv_evt_queue = xQueueCreateWithCaps(1, sizeof(i2c_slave_evt_t), I2C_MEM_ALLOC_CAPS);
ESP_GOTO_ON_FALSE((i2c_slave->slv_evt_queue != NULL), ESP_ERR_INVALID_STATE, err, TAG, "queue create failed");
int isr_flags = I2C_INTR_ALLOC_FLAG;
if (slave_config->intr_priority) {
isr_flags |= 1 << (slave_config->intr_priority);
}
ret = esp_intr_alloc_intrstatus(i2c_periph_signal[i2c_port_num].irq, isr_flags, (uint32_t)i2c_ll_get_interrupt_status_reg(hal->dev), I2C_LL_SLAVE_EVENT_INTR, s_slave_isr_handle_default, i2c_slave, &i2c_slave->base->intr_handle);
ESP_GOTO_ON_ERROR(ret, err, TAG, "install i2c slave interrupt failed");
ESP_RETURN_ON_FALSE(i2c_slave->tx_ring_buf, ESP_ERR_NO_MEM, TAG, "no memory for i2c slave transmit ringbuffer");
#if I2C_USE_RETENTION_LINK
if (slave_config->flags.allow_pd != 0) {
@@ -241,217 +293,153 @@ esp_err_t i2c_new_slave_device(const i2c_slave_config_t *slave_config, i2c_slave
}
#endif // I2C_USE_RETENTION_LINK
portENTER_CRITICAL(&i2c_slave->base->spinlock);
i2c_ll_clear_intr_mask(hal->dev, I2C_LL_SLAVE_EVENT_INTR);
i2c_hal_slave_init(hal);
#if SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
if (i2c_slave->fifo_mode == I2C_SLAVE_NONFIFO) {
i2c_ll_enable_fifo_mode(hal->dev, false);
i2c_ll_slave_enable_dual_addressing_mode(hal->dev, true);
} else {
i2c_ll_enable_fifo_mode(hal->dev, true);
i2c_ll_slave_enable_dual_addressing_mode(hal->dev, false);
int isr_flags = I2C_INTR_ALLOC_FLAG;
if (slave_config->intr_priority) {
isr_flags |= 1 << (slave_config->intr_priority);
}
#endif
ret = esp_intr_alloc_intrstatus(i2c_periph_signal[i2c_port_num].irq, isr_flags, (uint32_t)i2c_ll_get_interrupt_status_reg(hal->dev), I2C_LL_SLAVE_EVENT_INTR, i2c_slave_isr_handler, i2c_slave, &i2c_slave->base->intr_handle);
ESP_GOTO_ON_ERROR(ret, err, TAG, "install i2c slave interrupt failed");
portENTER_CRITICAL(&i2c_slave->base->spinlock);
i2c_hal_slave_init(hal);
i2c_ll_enable_fifo_mode(hal->dev, true);
i2c_ll_set_slave_addr(hal->dev, slave_config->slave_addr, false);
i2c_ll_set_tout(hal->dev, I2C_LL_MAX_TIMEOUT);
//Default, we enable hardware filter
I2C_CLOCK_SRC_ATOMIC() {
i2c_ll_set_source_clk(hal->dev, slave_config->clk_source);
}
bool addr_10bit_en = slave_config->addr_bit_len != I2C_ADDR_BIT_LEN_7;
i2c_ll_set_slave_addr(hal->dev, slave_config->slave_addr, addr_10bit_en);
#if SOC_I2C_SLAVE_SUPPORT_BROADCAST
i2c_ll_slave_broadcast_enable(hal->dev, slave_config->flags.broadcast_en);
#endif
i2c_ll_set_txfifo_empty_thr(hal->dev, I2C_FIFO_EMPTY_THRESH_VAL_DEFAULT);
i2c_ll_set_rxfifo_full_thr(hal->dev, I2C_FIFO_FULL_THRESH_VAL_DEFAULT);
// set timing for data
i2c_ll_set_sda_timing(hal->dev, 10, 10);
i2c_ll_set_tout(hal->dev, I2C_SLAVE_TIMEOUT_DEFAULT);
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
i2c_ll_slave_enable_scl_stretch(hal->dev, slave_config->flags.stretch_en);
#endif
i2c_ll_slave_enable_auto_start(hal->dev, true);
i2c_ll_set_txfifo_empty_thr(hal->dev, SOC_I2C_FIFO_LEN / 2);
i2c_ll_set_rxfifo_full_thr(hal->dev, SOC_I2C_FIFO_LEN / 2);
i2c_ll_set_sda_timing(hal->dev, 10, 10);
i2c_ll_disable_intr_mask(hal->dev, I2C_LL_INTR_MASK);
i2c_ll_clear_intr_mask(hal->dev, I2C_LL_INTR_MASK);
i2c_ll_enable_intr_mask(hal->dev, I2C_LL_SLAVE_RX_EVENT_INTR);
// Configure stretch
i2c_ll_slave_set_stretch_protect_num(hal->dev, I2C_LL_STRETCH_PROTECT_TIME);
i2c_ll_slave_enable_scl_stretch(hal->dev, true);
i2c_ll_slave_clear_stretch(hal->dev);
i2c_ll_update(hal->dev);
portEXIT_CRITICAL(&i2c_slave->base->spinlock);
xSemaphoreGive(i2c_slave->slv_rx_mux);
xSemaphoreGive(i2c_slave->slv_tx_mux);
*ret_handle = i2c_slave;
return ESP_OK;
return ret;
err:
if (i2c_slave) {
i2c_slave_bus_destroy(i2c_slave);
i2c_slave_device_destroy(i2c_slave);
}
return ret;
}
static esp_err_t i2c_slave_bus_destroy(i2c_slave_dev_handle_t i2c_slave)
{
if (i2c_slave) {
if (i2c_slave->base) {
i2c_ll_disable_intr_mask(i2c_slave->base->hal.dev, I2C_LL_SLAVE_EVENT_INTR);
i2c_common_deinit_pins(i2c_slave->base);
i2c_release_bus_handle(i2c_slave->base);
}
if (i2c_slave->slv_rx_mux) {
vSemaphoreDeleteWithCaps(i2c_slave->slv_rx_mux);
i2c_slave->slv_rx_mux = NULL;
}
if (i2c_slave->slv_tx_mux) {
vSemaphoreDeleteWithCaps(i2c_slave->slv_tx_mux);
i2c_slave->slv_tx_mux = NULL;
}
if (i2c_slave->tx_ring_buf) {
vRingbufferDeleteWithCaps(i2c_slave->tx_ring_buf);
i2c_slave->tx_ring_buf = NULL;
}
if (i2c_slave->slv_evt_queue) {
vQueueDeleteWithCaps(i2c_slave->slv_evt_queue);
}
}
free(i2c_slave);
return ESP_OK;
}
esp_err_t i2c_del_slave_device(i2c_slave_dev_handle_t i2c_slave)
{
ESP_RETURN_ON_FALSE(i2c_slave, ESP_ERR_INVALID_ARG, TAG, "i2c slave not initialized");
int port_id = i2c_slave->base->port_num;
ESP_LOGD(TAG, "del i2c bus(%d)", port_id);
ESP_RETURN_ON_ERROR(i2c_slave_bus_destroy(i2c_slave), TAG, "destroy i2c bus failed");
ESP_RETURN_ON_ERROR(i2c_slave_device_destroy(i2c_slave), TAG, "destroy i2c bus failed");
return ESP_OK;
}
esp_err_t i2c_slave_transmit(i2c_slave_dev_handle_t i2c_slave, const uint8_t *data, int size, int xfer_timeout_ms)
esp_err_t i2c_slave_write(i2c_slave_dev_handle_t i2c_slave, const uint8_t *data, uint32_t len, uint32_t *write_len, int timeout_ms)
{
ESP_RETURN_ON_FALSE(i2c_slave, ESP_ERR_INVALID_ARG, TAG, "i2c slave not initialized");
ESP_RETURN_ON_FALSE(data, ESP_ERR_INVALID_ARG, TAG, "invalid data buffer");
ESP_RETURN_ON_FALSE((i2c_slave->fifo_mode == I2C_SLAVE_FIFO), ESP_ERR_NOT_SUPPORTED, TAG, "non-fifo mode is not supported in this API, please set access_ram_en to false");
esp_err_t ret = ESP_OK;
ESP_RETURN_ON_FALSE(write_len, ESP_ERR_INVALID_ARG, TAG, "invalid write length pointer");
uint32_t free_fifo_len = 0;
uint32_t write_ringbuffer_len = 0;
uint32_t actual_write_fifo_size = 0;
uint8_t *existing_data = NULL;
size_t existing_size = 0;
i2c_hal_context_t *hal = &i2c_slave->base->hal;
#if CONFIG_IDF_TARGET_ESP32C5
// Workaround for c5 digital bug. Please note that following code has no
// functionality. It's just use for workaround the potential issue for avoiding
// secondary transaction.
i2c_ll_slave_enable_auto_start(hal->dev, true);
i2c_ll_start_trans(hal->dev);
i2c_ll_slave_enable_auto_start(hal->dev, false);
#endif
TickType_t wait_ticks = (xfer_timeout_ms == -1) ? portMAX_DELAY : pdMS_TO_TICKS(xfer_timeout_ms);
TickType_t wait_ticks = (timeout_ms == -1) ? portMAX_DELAY : pdMS_TO_TICKS(timeout_ms);
xSemaphoreTake(i2c_slave->operation_mux, wait_ticks);
ESP_RETURN_ON_FALSE(xSemaphoreTake(i2c_slave->slv_tx_mux, wait_ticks) == pdTRUE, ESP_ERR_TIMEOUT, TAG, "transmit timeout");
ESP_GOTO_ON_FALSE(xRingbufferSend(i2c_slave->tx_ring_buf, data, size, wait_ticks) == pdTRUE, ESP_ERR_INVALID_STATE, err, TAG, "no space in ringbuffer");
portENTER_CRITICAL(&i2c_slave->base->spinlock);
i2c_slave->trans_data_length += size;
i2c_ll_enable_intr_mask(hal->dev, I2C_LL_SLAVE_TX_EVENT_INTR);
#if !SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
i2c_ll_slave_disable_tx_it(hal->dev);
uint32_t txfifo_len = 0;
i2c_ll_get_txfifo_len(hal->dev, &txfifo_len);
if (txfifo_len < SOC_I2C_FIFO_LEN) {
// For the target (esp32) cannot stretch, reset the fifo when there is any dirty data in fifo.
i2c_ll_txfifo_rst(hal->dev);
}
#endif
i2c_ll_get_txfifo_len(hal->dev, &free_fifo_len);
portEXIT_CRITICAL(&i2c_slave->base->spinlock);
err:
xSemaphoreGive(i2c_slave->slv_tx_mux);
return ret;
}
esp_err_t i2c_slave_receive(i2c_slave_dev_handle_t i2c_slave, uint8_t *data, size_t receive_size)
{
ESP_RETURN_ON_FALSE(i2c_slave, ESP_ERR_INVALID_ARG, TAG, "i2c slave not initialized");
ESP_RETURN_ON_FALSE(data, ESP_ERR_INVALID_ARG, TAG, "invalid data buffer");
ESP_RETURN_ON_FALSE((i2c_slave->fifo_mode == I2C_SLAVE_FIFO), ESP_ERR_NOT_SUPPORTED, TAG, "non-fifo mode is not supported in this API, please set access_ram_en to false");
#if CONFIG_I2C_ISR_IRAM_SAFE
ESP_RETURN_ON_FALSE(esp_ptr_internal(data), ESP_ERR_INVALID_ARG, TAG, "buffer must locate in internal RAM if IRAM_SAFE is enabled");
#endif
i2c_hal_context_t *hal = &i2c_slave->base->hal;
#if CONFIG_IDF_TARGET_ESP32C5
// Workaround for c5 digital bug. Please note that following code has no
// functionality. It's just use for workaround the potential issue for avoiding
// secondary transaction.
i2c_ll_slave_enable_auto_start(hal->dev, true);
i2c_ll_start_trans(hal->dev);
i2c_ll_slave_enable_auto_start(hal->dev, false);
#endif
// Check if there is any data in the ringbuffer in last transaction
existing_data = xRingbufferReceiveUpTo(i2c_slave->tx_ring_buf, &existing_size, 0, free_fifo_len);
if (existing_data) {
// has data, fill to the fifo
i2c_ll_write_txfifo(hal->dev, existing_data, existing_size);
free_fifo_len -= existing_size;
vRingbufferReturnItem(i2c_slave->tx_ring_buf, existing_data);
}
xSemaphoreTake(i2c_slave->slv_rx_mux, portMAX_DELAY);
i2c_slave_receive_t *t = &i2c_slave->receive_desc;
t->buffer = data;
t->rcv_fifo_cnt = receive_size;
i2c_slave->already_receive_len = 0;
// Clear all interrupt raw bits before enable, avoid previous bus data affects interrupt.
i2c_ll_clear_intr_mask(hal->dev, I2C_LL_SLAVE_RX_EVENT_INTR);
i2c_ll_enable_intr_mask(hal->dev, I2C_LL_SLAVE_RX_EVENT_INTR);
return ESP_OK;
}
#if SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
esp_err_t i2c_slave_read_ram(i2c_slave_dev_handle_t i2c_slave, uint8_t ram_offset, uint8_t *data, size_t receive_size)
{
ESP_RETURN_ON_FALSE(i2c_slave, ESP_ERR_INVALID_ARG, TAG, "i2c slave not initialized");
ESP_RETURN_ON_FALSE(data, ESP_ERR_INVALID_ARG, TAG, "invalid data buffer");
ESP_RETURN_ON_FALSE((ram_offset + receive_size <= SOC_I2C_FIFO_LEN), ESP_ERR_INVALID_SIZE, TAG, "don't read data cross fifo boundary, see `SOC_I2C_FIFO_LEN`");
ESP_RETURN_ON_FALSE((i2c_slave->fifo_mode == I2C_SLAVE_NONFIFO), ESP_ERR_NOT_SUPPORTED, TAG, "fifo mode is not supported in this API, please set access_ram_en to true");
i2c_hal_context_t *hal = &i2c_slave->base->hal;
uint32_t fifo_size = 0;
portENTER_CRITICAL(&i2c_slave->base->spinlock);
i2c_ll_get_rxfifo_cnt(hal->dev, &fifo_size);
if (receive_size > fifo_size) {
ESP_LOGE(TAG, "receive size is so large that fifo has not so much data to get");
// Write data.
if (free_fifo_len) {
portENTER_CRITICAL(&i2c_slave->base->spinlock);
if (len < free_fifo_len) {
actual_write_fifo_size = len;
}
i2c_ll_write_txfifo(hal->dev, (uint8_t *)data, actual_write_fifo_size);
data += actual_write_fifo_size;
len -= actual_write_fifo_size;
portEXIT_CRITICAL(&i2c_slave->base->spinlock);
return ESP_ERR_INVALID_SIZE;
//write the rest of the bytes to the ringbuffer
}
i2c_ll_read_rx_by_nonfifo(hal->dev, ram_offset, data, fifo_size);
portEXIT_CRITICAL(&i2c_slave->base->spinlock);
if (len) {
write_ringbuffer_len = xRingbufferGetCurFreeSize(i2c_slave->tx_ring_buf);
if (len < write_ringbuffer_len) {
write_ringbuffer_len = len;
}
if (xRingbufferSend(i2c_slave->tx_ring_buf, data, write_ringbuffer_len, wait_ticks) != pdTRUE) {
write_ringbuffer_len = 0;
}
}
*write_len = write_ringbuffer_len + actual_write_fifo_size;
i2c_ll_slave_enable_tx_it(hal->dev);
i2c_ll_slave_clear_stretch(hal->dev);
xSemaphoreGive(i2c_slave->operation_mux);
return ESP_OK;
}
esp_err_t i2c_slave_write_ram(i2c_slave_dev_handle_t i2c_slave, uint8_t ram_offset, const uint8_t *data, size_t size)
{
ESP_RETURN_ON_FALSE(i2c_slave, ESP_ERR_INVALID_ARG, TAG, "i2c slave not initialized");
ESP_RETURN_ON_FALSE(data, ESP_ERR_INVALID_ARG, TAG, "invalid data buffer");
ESP_RETURN_ON_FALSE((i2c_slave->fifo_mode == I2C_SLAVE_NONFIFO), ESP_ERR_NOT_SUPPORTED, TAG, "fifo mode is not supported in this API, please set access_ram_en to true");
i2c_hal_context_t *hal = &i2c_slave->base->hal;
ESP_RETURN_ON_FALSE(xSemaphoreTake(i2c_slave->slv_tx_mux, portMAX_DELAY) == pdTRUE, ESP_ERR_TIMEOUT, TAG, "write to ram lock timeout");
uint32_t fifo_size = 0;
i2c_ll_txfifo_rst(hal->dev);
i2c_ll_get_txfifo_len(hal->dev, &fifo_size);
if (ram_offset + fifo_size < size) {
ESP_EARLY_LOGE(TAG, "No extra fifo to fill your buffer, please split your buffer");
return ESP_ERR_INVALID_SIZE;
}
i2c_ll_write_tx_by_nonfifo(hal->dev, ram_offset, data, size);
xSemaphoreGive(i2c_slave->slv_tx_mux);
return ESP_OK;
}
#endif
esp_err_t i2c_slave_register_event_callbacks(i2c_slave_dev_handle_t i2c_slave, const i2c_slave_event_callbacks_t *cbs, void *user_data)
{
ESP_RETURN_ON_FALSE(i2c_slave != NULL, ESP_ERR_INVALID_ARG, TAG, "i2c slave handle not initialized");
ESP_RETURN_ON_FALSE(cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument");
#if CONFIG_I2C_ISR_IRAM_SAFE
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
if (cbs->on_stretch_occur) {
ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_stretch_occur), ESP_ERR_INVALID_ARG, TAG, "i2c stretch occur callback not in IRAM");
if (cbs->on_request) {
ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_request), ESP_ERR_INVALID_ARG, TAG, "i2c request occur callback not in IRAM");
}
#endif // SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
if (cbs->on_recv_done) {
ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_recv_done), ESP_ERR_INVALID_ARG, TAG, "i2c receive done callback not in IRAM");
if (cbs->on_receive) {
ESP_RETURN_ON_FALSE(esp_ptr_in_iram(cbs->on_receive), ESP_ERR_INVALID_ARG, TAG, "i2c receive occur callback not in IRAM");
}
if (user_data) {
ESP_RETURN_ON_FALSE(esp_ptr_internal(user_data), ESP_ERR_INVALID_ARG, TAG, "user context not in internal RAM");
}
#endif // CONFIG_I2C_ISR_IRAM_SAFE
#endif
memcpy(&(i2c_slave->callbacks), cbs, sizeof(i2c_slave_event_callbacks_t));
i2c_slave->user_ctx = user_data;
i2c_slave->request_callback = cbs->on_request;
i2c_slave->receive_callback = cbs->on_receive;
return ESP_OK;
}

122
components/esp_driver_i2c/include/driver/i2c_slave.h
View File

@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -16,124 +16,6 @@
extern "C" {
#endif
#if !CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2
/**
* @brief I2C slave specific configurations
*/
typedef struct {
i2c_port_num_t i2c_port; /*!< I2C port number, `-1` for auto selecting */
gpio_num_t sda_io_num; /*!< SDA IO number used by I2C bus */
gpio_num_t scl_io_num; /*!< SCL IO number used by I2C bus */
i2c_clock_source_t clk_source; /*!< Clock source of I2C bus. */
uint32_t send_buf_depth; /*!< Depth of internal transfer ringbuffer, increase this value can support more transfers pending in the background */
uint16_t slave_addr; /*!< I2C slave address */
i2c_addr_bit_len_t addr_bit_len; /*!< I2C slave address in bit length */
int intr_priority; /*!< I2C interrupt priority, if set to 0, driver will select the default priority (1,2,3). */
struct {
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
uint32_t stretch_en: 1; /*!< Enable slave stretch */
#endif
#if SOC_I2C_SLAVE_SUPPORT_BROADCAST
uint32_t broadcast_en: 1; /*!< I2C slave enable broadcast */
#endif
#if SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
uint32_t access_ram_en: 1; /*!< Can get access to I2C RAM directly */
#endif
#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
uint32_t allow_pd: 1; /*!< If set, the driver will backup/restore the I2C registers before/after entering/exist sleep mode.
By this approach, the system can power off I2C's power domain.
This can save power, but at the expense of more RAM being consumed */
} flags; /*!< I2C slave config flags */
} i2c_slave_config_t;
/**
* @brief Group of I2C slave callbacks (e.g. get i2c slave stretch cause). But take care of potential concurrency issues.
* @note The callbacks are all running under ISR context
* @note When CONFIG_I2C_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM.
* The variables used in the function should be in the SRAM as well.
*/
typedef struct {
#if SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE
i2c_slave_stretch_callback_t on_stretch_occur; /*!< I2C slave stretched callback */
#endif
i2c_slave_received_callback_t on_recv_done; /*!< I2C slave receive done callback */
} i2c_slave_event_callbacks_t;
/**
* @brief Read bytes from I2C internal buffer. Start a job to receive I2C data.
*
* @note This function is non-blocking, it initiates a new receive job and then returns.
* User should check the received data from the `on_recv_done` callback that registered by `i2c_slave_register_event_callbacks()`.
*
* @param[in] i2c_slave I2C slave device handle that created by `i2c_new_slave_device`.
* @param[out] data Buffer to store data from I2C fifo. Should be valid until `on_recv_done` is triggered.
* @param[in] buffer_size Buffer size of data that provided by users.
* @return
* - ESP_OK: I2C slave receive success.
* - ESP_ERR_INVALID_ARG: I2C slave receive parameter invalid.
* - ESP_ERR_NOT_SUPPORTED: This function should be work in fifo mode, but I2C_SLAVE_NONFIFO mode is configured
*/
esp_err_t i2c_slave_receive(i2c_slave_dev_handle_t i2c_slave, uint8_t *data, size_t buffer_size);
/**
* @brief Write bytes to internal ringbuffer of the I2C slave data. When the TX fifo empty, the ISR will
* fill the hardware FIFO with the internal ringbuffer's data.
*
* @note If you connect this slave device to some master device, the data transaction direction is from slave
* device to master device.
*
* @param[in] i2c_slave I2C slave device handle that created by `i2c_new_slave_device`.
* @param[in] data Buffer to write to slave fifo, can pickup by master. Can be freed after this function returns. Equal or larger than `size`.
* @param[in] size In bytes, of `data` buffer.
* @param[in] xfer_timeout_ms Wait timeout, in ms. Note: -1 means wait forever.
* @return
* - ESP_OK: I2C slave transmit success.
* - ESP_ERR_INVALID_ARG: I2C slave transmit parameter invalid.
* - ESP_ERR_TIMEOUT: Operation timeout(larger than xfer_timeout_ms) because the device is busy or hardware crash.
* - ESP_ERR_NOT_SUPPORTED: This function should be work in fifo mode, but I2C_SLAVE_NONFIFO mode is configured
*/
esp_err_t i2c_slave_transmit(i2c_slave_dev_handle_t i2c_slave, const uint8_t *data, int size, int xfer_timeout_ms);
#if SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
/**
* @brief Read bytes from I2C internal ram. This can be only used when `access_ram_en` in configuration structure set to true.
*
* @param[in] i2c_slave I2C slave device handle that created by `i2c_new_slave_device`.
* @param[in] ram_address The offset of RAM (Cannot larger than I2C RAM memory)
* @param[out] data Buffer to store data read from I2C ram.
* @param[in] receive_size Received size from RAM.
* @return
* - ESP_OK: I2C slave transmit success.
* - ESP_ERR_INVALID_ARG: I2C slave transmit parameter invalid.
* - ESP_ERR_NOT_SUPPORTED: This function should be work in non-fifo mode, but I2C_SLAVE_FIFO mode is configured
*/
esp_err_t i2c_slave_read_ram(i2c_slave_dev_handle_t i2c_slave, uint8_t ram_address, uint8_t *data, size_t receive_size);
/**
* @brief Write bytes to I2C internal ram. This can be only used when `access_ram_en` in configuration structure set to true.
*
* @param[in] i2c_slave I2C slave device handle that created by `i2c_new_slave_device`.
* @param[in] ram_address The offset of RAM (Cannot larger than I2C RAM memory)
* @param[in] data Buffer to fill.
* @param[in] size Received size from RAM.
* @return
* - ESP_OK: I2C slave transmit success.
* - ESP_ERR_INVALID_ARG: I2C slave transmit parameter invalid.
* - ESP_ERR_INVALID_SIZE: Write size is larger than
* - ESP_ERR_NOT_SUPPORTED: This function should be work in non-fifo mode, but I2C_SLAVE_FIFO mode is configured
*/
esp_err_t i2c_slave_write_ram(i2c_slave_dev_handle_t i2c_slave, uint8_t ram_address, const uint8_t *data, size_t size);
#endif
#else // CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2
//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////// I2C SLAVE VERSION TWO /////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/**
* @brief I2C slave specific configurations
*/
@@ -184,8 +66,6 @@ typedef struct {
*/
esp_err_t i2c_slave_write(i2c_slave_dev_handle_t i2c_slave, const uint8_t *data, uint32_t len, uint32_t *write_len, int timeout_ms);
#endif // CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2
/**
* @brief Initialize an I2C slave device
*

2
components/esp_driver_i2c/include/driver/i2c_types.h
View File

@@ -106,9 +106,7 @@ typedef bool (*i2c_master_callback_t)(i2c_master_dev_handle_t i2c_dev, const i2c
*/
typedef struct {
uint8_t *buffer; /**< Pointer for buffer received in callback. */
#if CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2
uint32_t length; /**< Length for buffer received in callback. */
#endif
} i2c_slave_rx_done_event_data_t;
/**

1
components/esp_driver_i2c/test_apps/i2c_test_apps/sdkconfig.defaults
View File

@@ -1,3 +1,2 @@
CONFIG_FREERTOS_HZ=1000
CONFIG_ESP_TASK_WDT_INIT=n
CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2=y

10
docs/en/api-reference/peripherals/i2c.rst
View File

@@ -36,15 +36,6 @@ Typically, an I2C slave device has a 7-bit address or 10-bit address. {IDF_TARGE
Keep in mind that the higher the frequency, the smaller the pull-up resistor should be (but not less than 1 kΩ). Indeed, large resistors will decline the current, which will increase the clock switching time and reduce the frequency. A range of 2 kΩ to 5 kΩ is recommended, but adjustments may also be necessary depending on their current draw requirements.
.. toctree::
:hidden:
i2c_slave_v1
.. note::
We realized that our first version of the I2C slave driver had some problems and was not easy to use, so we have prepared a second version of the I2C slave driver, which solves many of the problems with our current I2C slave and which will be the focus of our maintenance. We encourage and recommend that you use the second version of the I2C slave driver, which you can do by enabling :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2`. This document focuses on the content of I2C slave v2.0. If you still want to read programming guide of I2C slave v1.0, please refer to :ref:`i2c-slave-v1`. The I2C slave v1.0 driver will be removed with the IDF v6.0 update.
I2C Clock Configuration
-----------------------
@@ -667,7 +658,6 @@ Kconfig Options
- :ref:`CONFIG_I2C_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see also `IRAM Safe <#iram-safe>`__ for more information.
- :ref:`CONFIG_I2C_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
- :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2` is used to enable the I2C slave driver v2.0.
Application Examples
--------------------

202
docs/en/api-reference/peripherals/i2c_slave_v1.rst
View File

@@ -1,202 +0,0 @@
.. _i2c-slave-v1:
I2C Slave v1.0
==============
.. warning::
This I2C slave driver version 1 will be removed when idf v6.0 update. We suggest you use I2C slave version 2 via :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2`.
After installing the I2C slave driver by :cpp:func:`i2c_new_slave_device`, {IDF_TARGET_NAME} is ready to communicate with other I2C masters as a slave.
Install I2C slave device
~~~~~~~~~~~~~~~~~~~~~~~~
I2C slave requires the configuration specified by :cpp:type:`i2c_slave_config_t`:
.. list::
- :cpp:member:`i2c_slave_config_t::i2c_port` sets the I2C port used by the controller.
- :cpp:member:`i2c_slave_config_t::sda_io_num` sets the GPIO number for serial data bus (SDA).
- :cpp:member:`i2c_slave_config_t::scl_io_num` sets the GPIO number for serial clock bus (SCL).
- :cpp:member:`i2c_slave_config_t::clk_source` selects the source clock for I2C bus. The available clocks are listed in :cpp:type:`i2c_clock_source_t`. For the effect on power consumption of different clock source, please refer to `Power Management <#power-management>`__ section.
- :cpp:member:`i2c_slave_config_t::send_buf_depth` sets the sending buffer length.
- :cpp:member:`i2c_slave_config_t::slave_addr` sets the slave address.
- :cpp:member:`i2c_slave_config_t::intr_priority` sets the priority of the interrupt. If set to ``0`` , then the driver will use a interrupt with low or medium priority (priority level may be one of 1, 2 or 3), otherwise use the priority indicated by :cpp:member:`i2c_slave_config_t::intr_priority`. Please use the number form (1, 2, 3), instead of the bitmask form ((1<<1), (1<<2), (1<<3)). Please pay attention that once the interrupt priority is set, it cannot be changed until :cpp:func:`i2c_del_slave_bus` is called.
- :cpp:member:`i2c_slave_config_t::addr_bit_len`. Set this variable to ``I2C_ADDR_BIT_LEN_10`` if the slave should have a 10-bit address.
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::stretch_en`. Set this variable to true, then the slave controller stretch will work. Please refer to [`TRM <{IDF_TARGET_TRM_EN_URL}#i2c>`__] to learn how I2C stretch works.
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::broadcast_en`. Set this to true to enable the slave broadcast. When the slave receives the general call address 0x00 from the master and the R/W bit followed is 0, it responds to the master regardless of its own address.
:SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS: - :cpp:member:`i2c_slave_config_t::access_ram_en`. Set this to true to enable the non-FIFO mode. Thus the I2C data FIFO can be used as RAM, and double addressing will be synchronised opened.
:SOC_I2C_SLAVE_SUPPORT_SLAVE_UNMATCH: - :cpp:member:`i2c_slave_config_t::slave_unmatch_en`. Set this to true to enable the slave unmatch interrupt. If the command address sent by master can't match the slave address, then unmatch interrupt will be triggered.
Once the :cpp:type:`i2c_slave_config_t` structure is populated with mandatory parameters, :cpp:func:`i2c_new_slave_device` can be called to allocate and initialize an I2C master bus. This function will return an I2C bus handle if it runs correctly. Specifically, when there are no more I2C port available, this function will return :c:macro:`ESP_ERR_NOT_FOUND` error.
.. code:: c
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
Uninstall I2C slave device
~~~~~~~~~~~~~~~~~~~~~~~~~~
If a previously installed I2C bus is no longer needed, it's recommended to recycle the resource by calling :cpp:func:`i2c_del_slave_device`, so that to release the underlying hardware.
I2C Slave Write
~~~~~~~~~~~~~~~
The send buffer of the I2C slave is used as a FIFO to store the data to be sent. The data will queue up until the master requests them. You can call :cpp:func:`i2c_slave_transmit` to transfer data.
Simple example for writing data to FIFO:
.. code:: c
uint8_t *data_wr = (uint8_t *) malloc(DATA_LENGTH);
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7, // 7-bit address
.clk_source = I2C_CLK_SRC_DEFAULT, // set the clock source
.i2c_port = TEST_I2C_PORT, // set I2C port number
.send_buf_depth = 256, // set TX buffer length
.scl_io_num = I2C_SLAVE_SCL_IO, // SCL GPIO number
.sda_io_num = I2C_SLAVE_SDA_IO, // SDA GPIO number
.slave_addr = 0x58, // slave address
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
for (int i = 0; i < DATA_LENGTH; i++) {
data_wr[i] = i;
}
ESP_ERROR_CHECK(i2c_slave_transmit(slave_handle, data_wr, DATA_LENGTH, 10000));
I2C Slave Read
~~~~~~~~~~~~~~
Whenever the master writes data to the slave, the slave will automatically store data in the receive buffer. This allows the slave application to call the function :cpp:func:`i2c_slave_receive` as its own discretion. As :cpp:func:`i2c_slave_receive` is designed as a non-blocking interface, users need to register callback :cpp:func:`i2c_slave_register_event_callbacks` to know when the receive has finished.
.. code:: c
static IRAM_ATTR bool i2c_slave_rx_done_callback(i2c_slave_dev_handle_t channel, const i2c_slave_rx_done_event_data_t *edata, void *user_data)
{
BaseType_t high_task_wakeup = pdFALSE;
QueueHandle_t receive_queue = (QueueHandle_t)user_data;
xQueueSendFromISR(receive_queue, edata, &high_task_wakeup);
return high_task_wakeup == pdTRUE;
}
uint8_t *data_rd = (uint8_t *) malloc(DATA_LENGTH);
uint32_t size_rd = 0;
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
s_receive_queue = xQueueCreate(1, sizeof(i2c_slave_rx_done_event_data_t));
i2c_slave_event_callbacks_t cbs = {
.on_recv_done = i2c_slave_rx_done_callback,
};
ESP_ERROR_CHECK(i2c_slave_register_event_callbacks(slave_handle, &cbs, s_receive_queue));
i2c_slave_rx_done_event_data_t rx_data;
ESP_ERROR_CHECK(i2c_slave_receive(slave_handle, data_rd, DATA_LENGTH));
xQueueReceive(s_receive_queue, &rx_data, pdMS_TO_TICKS(10000));
// Receive done.
.. only:: SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
Put Data In I2C Slave RAM
~~~~~~~~~~~~~~~~~~~~~~~~~
I2C slave FIFO mentioned above can be used as RAM, which means user can access the RAM directly via address fields. For example, write data to the third RAM block with following graph. Before using this, please note that :cpp:member:`i2c_slave_config_t::access_ram_en` needs to be set to true.
.. figure:: ../../../_static/diagrams/i2c/i2c_slave_write_slave_ram.png
:align: center
:alt: Put data in I2C slave RAM
Put data in I2C slave RAM
.. code:: c
uint8_t data_rd[DATA_LENGTH_RAM] = {0};
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
.flags.access_ram_en = true,
};
// Master writes to slave.
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
ESP_ERROR_CHECK(i2c_slave_read_ram(slave_handle, 0x5, data_rd, DATA_LENGTH_RAM));
ESP_ERROR_CHECK(i2c_del_slave_device(slave_handle));
Get Data From I2C Slave RAM
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Data can be stored in the RAM with a specific offset by the slave controller, and the master can read this data directly via the RAM address. For example, if the data is stored in the third RAM block, master can read this data by the following graph. Before using this, please note that :cpp:member:`i2c_slave_config_t::access_ram_en` needs to be set to true.
.. figure:: ../../../_static/diagrams/i2c/i2c_slave_read_slave_ram.png
:align: center
:alt: Get data from I2C slave RAM
Get data from I2C slave RAM
.. code:: c
uint8_t data_wr[DATA_LENGTH_RAM] = {0};
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
.flags.access_ram_en = true,
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
ESP_ERROR_CHECK(i2c_slave_write_ram(slave_handle, 0x2, data_wr, DATA_LENGTH_RAM));
ESP_ERROR_CHECK(i2c_del_slave_device(slave_handle));
I2C slave callbacks
~~~~~~~~~~~~~~~~~~~
When an I2C slave bus triggers an interrupt, a specific event will be generated and notify the CPU. If you have some function that needs to be called when those events occurred, you can hook your function to the ISR (Interrupt Service Routine) by calling :cpp:func:`i2c_slave_register_event_callbacks`. Since the registered callback functions are called in the interrupt context, users should ensure the callback function doesn't attempt to block (e.g. by making sure that only FreeRTOS APIs with ``ISR`` suffix are called from the function). The callback function has a boolean return value, to tell the caller whether a high priority task is woken up by it.
I2C slave event callbacks are listed in the :cpp:type:`i2c_slave_event_callbacks_t`.
.. list::
- :cpp:member:`i2c_slave_event_callbacks_t::on_recv_done` sets a callback function for "receive-done" event. The function prototype is declared in :cpp:type:`i2c_slave_received_callback_t`.
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_event_callbacks_t::on_stretch_occur` sets a callback function for "stretch" cause. The function prototype is declared in :cpp:type:`i2c_slave_stretch_callback_t`.

20
docs/en/migration-guides/release-6.x/6.0/peripherals.rst
View File

@@ -29,3 +29,23 @@ The ``pull_up`` and ``pull_down`` members have been removed from the following c
- :cpp:type:`mcpwm_gpio_fault_config_t`
- :cpp:type:`mcpwm_gpio_sync_src_config_t`
- :cpp:type:`mcpwm_capture_channel_config_t`
I2C
---
I2C slave has been redesigned in v5.4. In the current version, the old I2C slave driver has been removed. For details, please refer to the I2C slave section in the programming guide.
The major breaking changes in concept and usage are listed as follows:
Major Changes in Concepts
~~~~~~~~~~~~~~~~~~~~~~~~~
- Previously, the I2C slave driver performed active read and write operations. In the new version, these operations are handled passively via callbacks triggered by master events, aligning with standard I2C slave behavior.
Major Changes in Usage
~~~~~~~~~~~~~~~~~~~~~~
- ``i2c_slave_receive`` has been removed. In the new driver, data reception is handled via callbacks.
- ``i2c_slave_transmit`` has been replaced by ``i2c_slave_write``.
- ``i2c_slave_write_ram`` has been removed。
- ``i2c_slave_read_ram`` has been removed。

10
docs/zh_CN/api-reference/peripherals/i2c.rst
View File

@@ -36,15 +36,6 @@ I2C 是一种串行同步半双工通信协议，总线上可以同时挂载多
请注意，SCL 的频率越高，上拉电阻应该越小（但不能小于 1 kΩ）。较大的电阻会降低电流，增加时钟切换时间并降低频率。通常推荐 2 kΩ 到 5 kΩ 左右的电阻，也可根据电流需求进行一定调整。
.. toctree::
:hidden:
i2c_slave_v1
.. note::
我们发现 :ref:`i2c-slave-v1` 存在一些问题，且使用体验不够友好。为此，我们推出了 I2C 从机驱动 v2.0，此版本不仅解决了现有问题，还将成为我们未来的主要维护版本。我们建议并鼓励你使用 I2C 从机驱动 v2.0，你可以通过配置选项 :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2` 启用该功能。本文档主要介绍 I2C 从机驱动 v2.0 的功能。如果你想使用 I2C 从机驱动 v1.0，请参考 :ref:`i2c-slave-v1`。I2C 从机驱动 v1.0 将在 ESP-IDF v6.0 中移除。
I2C 时钟配置
------------
@@ -667,7 +658,6 @@ Kconfig 选项
- :ref:`CONFIG_I2C_ISR_IRAM_SAFE` 将在 cache 被禁用时控制默认的 ISR 处理程序正常工作，详情请参阅 `IRAM 安全 <#iram-safe>`__。
- :ref:`CONFIG_I2C_ENABLE_DEBUG_LOG` 可启用调试日志，但会增加固件二进制文件大小。
- :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2` 用于启用 I2C 从机驱动 v2.0 程序。
应用示例
--------

202
docs/zh_CN/api-reference/peripherals/i2c_slave_v1.rst
View File

@@ -1,202 +0,0 @@
.. _i2c-slave-v1:
I2C Slave v1.0
=================
.. warning::
该 I2C 从机驱动程序 v1.0 将在 ESP-IDF v6.0 中删除。我们建议你通过 :ref:`CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2` 使用 I2C 驱动程序 v2.0。
通过 :cpp:func:`i2c_new_slave_device` 安装 I2C 从机驱动程序后，{IDF_TARGET_NAME} 就可以作为从站与其他 I2C Master 通信了。
安装 I2C 从机设备
~~~~~~~~~~~~~~~~~~~
I2C 从机设备需要 :cpp:type:`i2c_slave_config_t` 指定的配置：
.. list::
- :cpp:member:`i2c_slave_config_t::i2c_port` 设置控制器使用的 I2C 端口。
- :cpp:member:`i2c_slave_config_t::sda_io_num` 设置串行数据总线 (SDA) 的 GPIO 编号。
- :cpp:member:`i2c_slave_config_t::scl_io_num` 设置串行时钟总线 (SCL) 的 GPIO 编号。
- :cpp:member:`i2c_slave_config_t::clk_source` 选择 I2C 总线的时钟源。可用时钟列表见 :cpp:type:`i2c_clock_source_t`。有关不同时钟源对功耗的影响，请参阅 `电源管理 <#power-management>`__。
- :cpp:member:`i2c_slave_config_t::send_buf_depth` 设置发送 buffer 的长度。
- :cpp:member:`i2c_slave_config_t::slave_addr` 设置从机地址。
- :cpp:member:`i2c_slave_config_t::intr_priority` 设置中断的优先级。如果设置为 ``0`` ，则驱动程序将使用低或中优先级的中断（优先级可设为 1、2 或 3 中的一个），若未设置，则将使用 :cpp:member:`i2c_slave_config_t::intr_priority` 指示的优先级。请使用数字形式（1、2、3），不要用位掩码形式（(1<<1)、(1<<2)、(1<<3)）。请注意，中断优先级一旦设置完成，在调用 :cpp:func:`i2c_del_slave_bus` 之前都无法更改。
- :cpp:member:`i2c_slave_config_t::addr_bit_len`。如果需要从机设备具有 10 位地址，则将该成员变量设为 ``I2C_ADDR_BIT_LEN_10``。
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::stretch_en`。如果要启用从机控制器拉伸功能，请将该成员变量设为 true。有关 I2C 拉伸的工作原理，请参阅 [`TRM <{IDF_TARGET_TRM_EN_URL}#i2c>`__]。
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_config_t::broadcast_en`。如果要启用从机广播，请将该成员变量设为 true。当从机设备接收到来自主机设备的通用调用地址 0x00，且后面的读写位为 0 时，无论从机设备自身地址如何，都会响应主机设备。
:SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS: - :cpp:member:`i2c_slave_config_t::access_ram_en`。如果要启用 non-FIFO 模式，请将该成员变量设为 true，则 I2C 数据 FIFO 可用作 RAM，并将同步打开双地址。
:SOC_I2C_SLAVE_SUPPORT_SLAVE_UNMATCH: - :cpp:member:`i2c_slave_config_t::slave_unmatch_en`。将该成员变量设为 true，将启用从机设备不匹配中断。如果主机设备发送的命令地址与从机设备地址不匹配，则会触发不匹配中断。
一旦填充好 :cpp:type:`i2c_slave_config_t` 结构体的必要参数，就可调用 :cpp:func:`i2c_new_slave_device` 来分配和初始化 I2C 主机总线。如果函数运行正确，则将返回一个 I2C 总线句柄。若没有可用的 I2C 端口，此函数将返回 :c:macro:`ESP_ERR_NOT_FOUND` 错误。
.. code:: c
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
卸载 I2C 从机设备
~~~~~~~~~~~~~~~~~~
如果不再需要之前安装的 I2C 总线，建议调用 :cpp:func:`i2c_del_slave_device` 来回收资源，以释放底层硬件。
I2C 从机写入
~~~~~~~~~~~~~
I2C 从机的发送 buffer 可作为 FIFO 来存储要发送的数据。在主机请求这些数据前，它们会一直排队。可通过调用 :cpp:func:`i2c_slave_transmit` 来传输数据。
将数据写入 FIFO 的简单示例：
.. code:: c
uint8_t *data_wr = (uint8_t *) malloc(DATA_LENGTH);
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7, // 7 位地址
.clk_source = I2C_CLK_SRC_DEFAULT, // 设置时钟源
.i2c_port = TEST_I2C_PORT, // 设置 I2C 端口编号
.send_buf_depth = 256, // 设置 TX buffer 长度
.scl_io_num = I2C_SLAVE_SCL_IO, // SCL 管脚编号
.sda_io_num = I2C_SLAVE_SDA_IO, // SDA 管脚编号
.slave_addr = 0x58, // 从机地址
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
for (int i = 0; i < DATA_LENGTH; i++) {
data_wr[i] = i;
}
ESP_ERROR_CHECK(i2c_slave_transmit(slave_handle, data_wr, DATA_LENGTH, 10000));
I2C 从机读取
~~~~~~~~~~~~~
每当主机将数据写入从机，从机都会自动将数据存储在接收 buffer 中，从而使从机应用程序能自由调用 :cpp:func:`i2c_slave_receive`。:cpp:func:`i2c_slave_receive` 为非阻塞接口，因此要想知道接收是否完成，需注册回调函数 :cpp:func:`i2c_slave_register_event_callbacks`。
.. code:: c
static IRAM_ATTR bool i2c_slave_rx_done_callback(i2c_slave_dev_handle_t channel, const i2c_slave_rx_done_event_data_t *edata, void *user_data)
{
BaseType_t high_task_wakeup = pdFALSE;
QueueHandle_t receive_queue = (QueueHandle_t)user_data;
xQueueSendFromISR(receive_queue, edata, &high_task_wakeup);
return high_task_wakeup == pdTRUE;
}
uint8_t *data_rd = (uint8_t *) malloc(DATA_LENGTH);
uint32_t size_rd = 0;
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
s_receive_queue = xQueueCreate(1, sizeof(i2c_slave_rx_done_event_data_t));
i2c_slave_event_callbacks_t cbs = {
.on_recv_done = i2c_slave_rx_done_callback,
};
ESP_ERROR_CHECK(i2c_slave_register_event_callbacks(slave_handle, &cbs, s_receive_queue));
i2c_slave_rx_done_event_data_t rx_data;
ESP_ERROR_CHECK(i2c_slave_receive(slave_handle, data_rd, DATA_LENGTH));
xQueueReceive(s_receive_queue, &rx_data, pdMS_TO_TICKS(10000));
// 接收完成。
.. only:: SOC_I2C_SLAVE_SUPPORT_I2CRAM_ACCESS
将数据放入 I2C 从机 RAM 中
~~~~~~~~~~~~~~~~~~~~~~~~~~~
如上所述，I2C 从机 FIFO 可被用作 RAM，即可以通过地址字段直接访问 RAM。例如，可参照下图将数据写入第三个 RAM 块。请注意，在进行操作前需要先将 :cpp:member:`i2c_slave_config_t::access_ram_en` 设为 true。
.. figure:: ../../../_static/diagrams/i2c/i2c_slave_write_slave_ram.png
:align: center
:alt: 将数据放入 I2C 从机 RAM 中
将数据放入 I2C 从机 RAM 中
.. code:: c
uint8_t data_rd[DATA_LENGTH_RAM] = {0};
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
.flags.access_ram_en = true,
};
// 主机将数据写入从机。
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
ESP_ERROR_CHECK(i2c_slave_read_ram(slave_handle, 0x5, data_rd, DATA_LENGTH_RAM));
ESP_ERROR_CHECK(i2c_del_slave_device(slave_handle));
从 I2C 从机 RAM 中获取数据
~~~~~~~~~~~~~~~~~~~~~~~~~~~
数据可被存储在相对从机一定偏移量的 RAM 中，且主机可直接通过 RAM 地址读取这些数据。例如，如果数据被存储在第三个 RAM 块中，则主机可参照下图读取这些数据。请注意，在操作前需要先将 :cpp:member:`i2c_slave_config_t::access_ram_en` 设为 true。
.. figure:: ../../../_static/diagrams/i2c/i2c_slave_read_slave_ram.png
:align: center
:alt: 从 I2C 从机 RAM 中获取数据
从 I2C 从机 RAM 中获取数据
.. code:: c
uint8_t data_wr[DATA_LENGTH_RAM] = {0};
i2c_slave_config_t i2c_slv_config = {
.addr_bit_len = I2C_ADDR_BIT_LEN_7,
.clk_source = I2C_CLK_SRC_DEFAULT,
.i2c_port = TEST_I2C_PORT,
.send_buf_depth = 256,
.scl_io_num = I2C_SLAVE_SCL_IO,
.sda_io_num = I2C_SLAVE_SDA_IO,
.slave_addr = 0x58,
.flags.access_ram_en = true,
};
i2c_slave_dev_handle_t slave_handle;
ESP_ERROR_CHECK(i2c_new_slave_device(&i2c_slv_config, &slave_handle));
ESP_ERROR_CHECK(i2c_slave_write_ram(slave_handle, 0x2, data_wr, DATA_LENGTH_RAM));
ESP_ERROR_CHECK(i2c_del_slave_device(slave_handle));
I2C 从机回调
~~~~~~~~~~~~~
当 I2C 从机总线触发中断时，将生成特定事件并通知 CPU。如果需要在发生这些事件时调用某些函数，可通过 :cpp:func:`i2c_slave_register_event_callbacks` 将这些函数挂接到中断服务程序 (ISR) 上。由于注册的回调函数是在中断上下文中被调用的，所以应确保这些函数不会导致延迟（例如，确保仅从函数中调用带有 ``ISR`` 后缀的 FreeRTOS API）。回调函数需要返回一个布尔值，告诉调用者是否唤醒了高优先级任务。
I2C 从机事件回调函数列表见 :cpp:type:`i2c_slave_event_callbacks_t`。
.. list::
- :cpp:member:`i2c_slave_event_callbacks_t::on_recv_done` 可设置用于“接收完成”事件的回调函数。该函数原型在 :cpp:type:`i2c_slave_received_callback_t` 中声明。
:SOC_I2C_SLAVE_CAN_GET_STRETCH_CAUSE: - :cpp:member:`i2c_slave_event_callbacks_t::on_stretch_occur` 可设置用于“时钟拉伸”事件的回调函数。该函数原型在 :cpp:type:`i2c_slave_stretch_callback_t` 中声明。

20
docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst
View File

@@ -29,3 +29,23 @@ MCPWM
- :cpp:type:`mcpwm_gpio_fault_config_t`
- :cpp:type:`mcpwm_gpio_sync_src_config_t`
- :cpp:type:`mcpwm_capture_channel_config_t`
I2C
---
I2C 从机在 v5.4 上已经被重新设计。在当前版本上，老的 I2C 从机驱动已经被移除，详细内容请参考编程指南中关于 I2C 从机的部分。
主要的概念上和用法上的改变如下所示:
主要概念更新
~~~~~~~~~~~~~~~~~~
- 老版本的 I2C 从机驱动是主动读写，这不符合 I2C 从机的一般用法。在新版的 I2C 从机中，I2C 的读写通过主机驱动产生的事件以触发回调被动完成。
主要用法更新
~~~~~~~~~~~~~~~~~~
- ``i2c_slave_receive`` 被移除， 在新驱动中使用回调接收数据。
- ``i2c_slave_transmit`` 已被 ``i2c_slave_write`` 取代.
- ``i2c_slave_write_ram`` 被移除。
- ``i2c_slave_read_ram`` 被移除。

1
examples/peripherals/i2c/i2c_slave_network_sensor/sdkconfig.defaults
View File

@@ -1,5 +1,4 @@
CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
CONFIG_I2C_ENABLE_SLAVE_DRIVER_VERSION_2=y
CONFIG_ESP_TLS_INSECURE=y
CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY=y