mirror of
https://github.com/espressif/esp-idf.git
synced 2025-11-03 14:01:53 +00:00
refactor(i2c): Add disclaimer for legacy driver
This commit is contained in:
Chen Chen
@@ -4,6 +4,14 @@ menu "Legacy Driver Configurations"
|
||||
|
||||
menu "Legacy I2C Driver Configurations"
|
||||
depends on SOC_I2C_SUPPORTED
|
||||
config I2C_SUPPRESS_DEPRECATE_WARN
|
||||
bool "Suppress legacy driver deprecated warning"
|
||||
default n
|
||||
help
|
||||
whether to suppress the deprecation warnings when using legacy i2c driver
|
||||
(driver/i2c.h). If you want to continue using the legacy driver,
|
||||
and don't want to see related deprecation warnings, you can enable this option.
|
||||
|
||||
config I2C_SKIP_LEGACY_CONFLICT_CHECK
|
||||
bool "Skip legacy conflict check"
|
||||
default n
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
#include "hal/i2c_hal.h"
|
||||
#include "hal/gpio_hal.h"
|
||||
#include "soc/i2c_periph.h"
|
||||
#include "driver/i2c.h"
|
||||
#include "driver/i2c_types_legacy.h"
|
||||
#include "esp_private/periph_ctrl.h"
|
||||
#include "esp_rom_gpio.h"
|
||||
#include "esp_rom_sys.h"
|
||||
@@ -254,6 +254,17 @@ static void i2c_isr_handler_default(void *arg);
|
||||
static void i2c_master_cmd_begin_static(i2c_port_t i2c_num, BaseType_t* HPTaskAwoken);
|
||||
static esp_err_t i2c_hw_fsm_reset(i2c_port_t i2c_num);
|
||||
|
||||
// Forward declarations for functions used before their definitions
|
||||
esp_err_t i2c_set_pin(i2c_port_t i2c_num, gpio_num_t sda_io_num, gpio_num_t scl_io_num, bool sda_pullup_en, bool scl_pullup_en, i2c_mode_t mode);
|
||||
i2c_cmd_handle_t i2c_cmd_link_create_static(uint8_t* buffer, uint32_t size);
|
||||
void i2c_cmd_link_delete_static(i2c_cmd_handle_t cmd_handle);
|
||||
esp_err_t i2c_master_start(i2c_cmd_handle_t cmd_handle);
|
||||
esp_err_t i2c_master_stop(i2c_cmd_handle_t cmd_handle);
|
||||
esp_err_t i2c_master_write(i2c_cmd_handle_t cmd_handle, const uint8_t *data, size_t data_len, bool ack_en);
|
||||
esp_err_t i2c_master_write_byte(i2c_cmd_handle_t cmd_handle, uint8_t data, bool ack_en);
|
||||
esp_err_t i2c_master_read(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len, i2c_ack_type_t ack);
|
||||
esp_err_t i2c_master_cmd_begin(i2c_port_t i2c_num, i2c_cmd_handle_t cmd_handle, TickType_t ticks_to_wait);
|
||||
|
||||
static void i2c_hw_disable(i2c_port_t i2c_num)
|
||||
{
|
||||
I2C_ENTER_CRITICAL(&(i2c_context[i2c_num].spinlock));
|
||||
|
||||
@@ -6,76 +6,33 @@
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "freertos/FreeRTOS.h"
|
||||
#include "esp_types.h"
|
||||
#include "esp_err.h"
|
||||
#include "esp_intr_alloc.h" // for intr_alloc_flags
|
||||
#include "soc/soc_caps.h"
|
||||
#include "hal/i2c_types.h"
|
||||
#include "hal/gpio_types.h"
|
||||
#include "sdkconfig.h"
|
||||
#include "driver/i2c_types_legacy.h"
|
||||
|
||||
#if !CONFIG_I2C_SUPPRESS_DEPRECATE_WARN
|
||||
#pragma message("\n" \
|
||||
"================================ CRITICAL WARNING ================================\n" \
|
||||
"This legacy I2C driver (driver/i2c.h) is officially END-OF-LIFE (EOL) as of ESP-IDF v6.0.\n" \
|
||||
"\n" \
|
||||
"1. NO SUPPORT: ESP-IDF will not provide updates, bug fixes, or security patches timely.\n" \
|
||||
"2. PLANNED REMOVAL: This driver WILL BE REMOVED in ESP-IDF v7.0 (next major release).\n" \
|
||||
"3. ACTION REQUIRED: Migrate to 'driver/i2c_master.h' or 'driver/i2c_slave.h' immediately.\n" \
|
||||
" - If you are a library maintainer, please update your code.\n" \
|
||||
" - If you are using 3rd-party libraries, contact the authors for updates.\n" \
|
||||
"\n" \
|
||||
"4. SUPPRESS WARNING: Set Kconfig 'CONFIG_I2C_SUPPRESS_DEPRECATE_WARN=y' to silent\n" \
|
||||
" this warning. However, by doing so, YOU ASSUME ALL RISKS including potential\n" \
|
||||
" security vulnerabilities, system instability, and future incompatibility.\n" \
|
||||
"\n" \
|
||||
"For API reference of the new I2C driver, see: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/i2c.html\n" \
|
||||
"For other items about migration, see: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/index.html\n" \
|
||||
"==================================================================================\n")
|
||||
#endif // !CONFIG_I2C_SUPPRESS_DEPRECATE_WARN
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
// I2C clk flags for users to use, can be expanded in the future.
|
||||
#define I2C_SCLK_SRC_FLAG_FOR_NOMAL (0) /*!< Any one clock source that is available for the specified frequency may be chosen*/
|
||||
#define I2C_SCLK_SRC_FLAG_AWARE_DFS (1 << 0) /*!< For REF tick clock, it won't change with APB.*/
|
||||
#define I2C_SCLK_SRC_FLAG_LIGHT_SLEEP (1 << 1) /*!< For light sleep mode.*/
|
||||
|
||||
/**
|
||||
* @brief Minimum size, in bytes, of the internal private structure used to describe
|
||||
* I2C commands link.
|
||||
*/
|
||||
#define I2C_INTERNAL_STRUCT_SIZE (24)
|
||||
|
||||
/**
|
||||
* @brief The following macro is used to determine the recommended size of the
|
||||
* buffer to pass to `i2c_cmd_link_create_static()` function.
|
||||
* It requires one parameter, `TRANSACTIONS`, describing the number of transactions
|
||||
* intended to be performed on the I2C port.
|
||||
* For example, if one wants to perform a read on an I2C device register, `TRANSACTIONS`
|
||||
* must be at least 2, because the commands required are the following:
|
||||
* - write device register
|
||||
* - read register content
|
||||
*
|
||||
* Signals such as "(repeated) start", "stop", "nack", "ack" shall not be counted.
|
||||
*/
|
||||
#define I2C_LINK_RECOMMENDED_SIZE(TRANSACTIONS) (2 * I2C_INTERNAL_STRUCT_SIZE + I2C_INTERNAL_STRUCT_SIZE * \
|
||||
(5 * TRANSACTIONS)) /* Make the assumption that each transaction
|
||||
* of the user is surrounded by a "start", device address
|
||||
* and a "nack/ack" signal. Allocate one more room for
|
||||
* "stop" signal at the end.
|
||||
* Allocate 2 more internal struct size for headers.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief I2C initialization parameters
|
||||
*/
|
||||
typedef struct {
|
||||
i2c_mode_t mode; /*!< I2C mode */
|
||||
gpio_num_t sda_io_num; /*!< GPIO number for I2C sda signal */
|
||||
gpio_num_t scl_io_num; /*!< GPIO number for I2C scl signal */
|
||||
bool sda_pullup_en; /*!< Internal GPIO pull mode for I2C sda signal*/
|
||||
bool scl_pullup_en; /*!< Internal GPIO pull mode for I2C scl signal*/
|
||||
|
||||
union {
|
||||
struct {
|
||||
uint32_t clk_speed; /*!< I2C clock frequency for master mode, (no higher than 1MHz for now) */
|
||||
} master; /*!< I2C master config */
|
||||
#if SOC_I2C_SUPPORT_SLAVE
|
||||
struct {
|
||||
uint8_t addr_10bit_en; /*!< I2C 10bit address mode enable for slave mode */
|
||||
uint16_t slave_addr; /*!< I2C address for slave mode */
|
||||
uint32_t maximum_speed; /*!< I2C expected clock speed from SCL. */
|
||||
} slave; /*!< I2C slave config */
|
||||
#endif // SOC_I2C_SUPPORT_SLAVE
|
||||
};
|
||||
uint32_t clk_flags; /*!< Bitwise of ``I2C_SCLK_SRC_FLAG_**FOR_DFS**`` for clk source choice*/
|
||||
} i2c_config_t;
|
||||
|
||||
typedef void *i2c_cmd_handle_t; /*!< I2C command handle */
|
||||
|
||||
/**
|
||||
* @brief Install an I2C driver
|
||||
* @note Not all Espressif chips can support slave mode (e.g. ESP32C2)
|
||||
|
||||
81
components/driver/i2c/include/driver/i2c_types_legacy.h
Normal file
81
components/driver/i2c/include/driver/i2c_types_legacy.h
Normal file
@@ -0,0 +1,81 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "freertos/FreeRTOS.h"
|
||||
#include "esp_types.h"
|
||||
#include "esp_err.h"
|
||||
#include "esp_intr_alloc.h" // for intr_alloc_flags
|
||||
#include "soc/soc_caps.h"
|
||||
#include "hal/i2c_types.h"
|
||||
#include "hal/gpio_types.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
// I2C clk flags for users to use, can be expanded in the future.
|
||||
#define I2C_SCLK_SRC_FLAG_FOR_NOMAL (0) /*!< Any one clock source that is available for the specified frequency may be chosen*/
|
||||
#define I2C_SCLK_SRC_FLAG_AWARE_DFS (1 << 0) /*!< For REF tick clock, it won't change with APB.*/
|
||||
#define I2C_SCLK_SRC_FLAG_LIGHT_SLEEP (1 << 1) /*!< For light sleep mode.*/
|
||||
|
||||
/**
|
||||
* @brief Minimum size, in bytes, of the internal private structure used to describe
|
||||
* I2C commands link.
|
||||
*/
|
||||
#define I2C_INTERNAL_STRUCT_SIZE (24)
|
||||
|
||||
/**
|
||||
* @brief The following macro is used to determine the recommended size of the
|
||||
* buffer to pass to `i2c_cmd_link_create_static()` function.
|
||||
* It requires one parameter, `TRANSACTIONS`, describing the number of transactions
|
||||
* intended to be performed on the I2C port.
|
||||
* For example, if one wants to perform a read on an I2C device register, `TRANSACTIONS`
|
||||
* must be at least 2, because the commands required are the following:
|
||||
* - write device register
|
||||
* - read register content
|
||||
*
|
||||
* Signals such as "(repeated) start", "stop", "nack", "ack" shall not be counted.
|
||||
*/
|
||||
#define I2C_LINK_RECOMMENDED_SIZE(TRANSACTIONS) (2 * I2C_INTERNAL_STRUCT_SIZE + I2C_INTERNAL_STRUCT_SIZE * \
|
||||
(5 * TRANSACTIONS)) /* Make the assumption that each transaction
|
||||
* of the user is surrounded by a "start", device address
|
||||
* and a "nack/ack" signal. Allocate one more room for
|
||||
* "stop" signal at the end.
|
||||
* Allocate 2 more internal struct size for headers.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief I2C initialization parameters
|
||||
*/
|
||||
typedef struct {
|
||||
i2c_mode_t mode; /*!< I2C mode */
|
||||
gpio_num_t sda_io_num; /*!< GPIO number for I2C sda signal */
|
||||
gpio_num_t scl_io_num; /*!< GPIO number for I2C scl signal */
|
||||
bool sda_pullup_en; /*!< Internal GPIO pull mode for I2C sda signal*/
|
||||
bool scl_pullup_en; /*!< Internal GPIO pull mode for I2C scl signal*/
|
||||
|
||||
union {
|
||||
struct {
|
||||
uint32_t clk_speed; /*!< I2C clock frequency for master mode, (no higher than 1MHz for now) */
|
||||
} master; /*!< I2C master config */
|
||||
#if SOC_I2C_SUPPORT_SLAVE
|
||||
struct {
|
||||
uint8_t addr_10bit_en; /*!< I2C 10bit address mode enable for slave mode */
|
||||
uint16_t slave_addr; /*!< I2C address for slave mode */
|
||||
uint32_t maximum_speed; /*!< I2C expected clock speed from SCL. */
|
||||
} slave; /*!< I2C slave config */
|
||||
#endif // SOC_I2C_SUPPORT_SLAVE
|
||||
};
|
||||
uint32_t clk_flags; /*!< Bitwise of ``I2C_SCLK_SRC_FLAG_**FOR_DFS**`` for clk source choice*/
|
||||
} i2c_config_t;
|
||||
|
||||
typedef void *i2c_cmd_handle_t; /*!< I2C command handle */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
@@ -1,2 +1,4 @@
|
||||
CONFIG_FREERTOS_HZ=1000
|
||||
CONFIG_ESP_TASK_WDT=n
|
||||
CONFIG_ESP_TASK_WDT_INIT=n
|
||||
|
||||
CONFIG_I2C_SUPPRESS_DEPRECATE_WARN=y
|
||||
|
||||
@@ -6,14 +6,13 @@
|
||||
|
||||
#include <stdio.h>
|
||||
#include "esp_log.h"
|
||||
#include "hal/i2c_ll.h"
|
||||
#include "soc/io_mux_reg.h"
|
||||
#include "soc/periph_defs.h"
|
||||
#include "soc/gpio_sig_map.h"
|
||||
#include "hal/gpio_ll.h"
|
||||
#include "hal/gpio_hal.h"
|
||||
#include "esp_rom_gpio.h"
|
||||
#include "hal/i2c_ll.h"
|
||||
#include "esp_rom_gpio.h"
|
||||
#include "esp_cpu.h"
|
||||
#include "esp_check.h"
|
||||
#include "esp_private/periph_ctrl.h"
|
||||
|
||||
@@ -3,3 +3,5 @@ CONFIG_ESP_TASK_WDT_INIT=n
|
||||
CONFIG_ULP_COPROC_ENABLED=y
|
||||
CONFIG_ULP_COPROC_TYPE_LP_CORE=y
|
||||
CONFIG_ULP_COPROC_RESERVE_MEM=12000
|
||||
|
||||
CONFIG_I2C_SUPPRESS_DEPRECATE_WARN=y
|
||||
|
||||
@@ -3,3 +3,5 @@ CONFIG_ESP_TASK_WDT_EN=n
|
||||
CONFIG_ULP_COPROC_ENABLED=y
|
||||
CONFIG_ULP_COPROC_TYPE_RISCV=y
|
||||
CONFIG_ULP_COPROC_RESERVE_MEM=4096
|
||||
|
||||
CONFIG_I2C_SUPPRESS_DEPRECATE_WARN=y
|
||||
|
||||
@@ -12,6 +12,8 @@ Peripherals
|
||||
|
||||
.. only:: SOC_I2C_SUPPORTED
|
||||
|
||||
.. _migration_guide_i2c_driver_5_2:
|
||||
|
||||
I2C
|
||||
---
|
||||
|
||||
|
||||
@@ -138,29 +138,47 @@ UART
|
||||
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.
|
||||
Legacy I2C Driver End-of-Life
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The major breaking changes in concept and usage are listed as follows:
|
||||
.. warning::
|
||||
|
||||
The legacy I2C driver (``driver/i2c.h``) has been marked as **End-of-Life (EOL)** in ESP-IDF v6.0 and is scheduled for **removal in v7.0**.
|
||||
|
||||
- ESP-IDF will not provide updates, bug fixes, or security patches for the legacy driver timely.
|
||||
- Users are strongly recommended to migrate to the new I2C drivers: ``driver/i2c_master.h`` and ``driver/i2c_slave.h``.
|
||||
- To temporarily suppress the compile-time warning, enable ``Component config`` > ``Legacy Driver Configurations`` > ``Legacy I2C Driver Configurations`` > ``Suppress legacy driver deprecated warning`` in menuconfig.
|
||||
|
||||
The new I2C drivers provide improved slave and master functionality. For details, please refer to the :ref:`I2C Migration Guide <migration_guide_i2c_driver_5_2>` and the :doc:`I2C Driver Programming Guide <../../../api-reference/peripherals/i2c>`.
|
||||
|
||||
I2C Slave Driver Updates
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The I2C slave driver has been redesigned in v5.4. In the current version, the old I2C slave driver has been removed.
|
||||
|
||||
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.
|
||||
|
||||
Meanwhile, I2C master also has some change in its APIs' definitions.
|
||||
I2C Master Driver Updates
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The I2C master driver also has some changes in its API definitions.
|
||||
|
||||
Major Changes in Usage
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Following functions now will return ``ESP_ERR_INVALID_RESPONSE`` instead of ``ESP_ERR_INVALID_STATE`` when NACK from the bus is detected:
|
||||
|
||||
- ``i2c_master_transmit``
|
||||
- ``i2c_master_multi_buffer_transmit``
|
||||
- ``i2c_master_transmit_receive``
|
||||
|
||||
@@ -12,6 +12,8 @@
|
||||
|
||||
.. only:: SOC_I2C_SUPPORTED
|
||||
|
||||
.. _migration_guide_i2c_driver_5_2:
|
||||
|
||||
I2C
|
||||
---
|
||||
|
||||
|
||||
@@ -138,29 +138,47 @@ UART
|
||||
I2C
|
||||
---
|
||||
|
||||
I2C 从机在 v5.4 上已经被重新设计。在当前版本上，老的 I2C 从机驱动已经被移除，详细内容请参考编程指南中关于 I2C 从机的部分。
|
||||
旧版 I2C 驱动生命周期终止
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
主要的概念上和用法上的改变如下所示:
|
||||
.. warning::
|
||||
|
||||
旧版 I2C 驱动（``driver/i2c.h``）已在 ESP-IDF v6.0 中被标记为 **生命周期终止（End-of-Life, EOL）**，并计划在 **v7.0 中彻底移除**。
|
||||
|
||||
- ESP-IDF 将不再为旧版驱动提供及时的更新、错误修复或安全补丁。
|
||||
- 强烈建议用户尽快迁移到新版 I2C 驱动：``driver/i2c_master.h`` 和 ``driver/i2c_slave.h``。
|
||||
- 如需暂时抑制编译警告，可在 menuconfig 中启用 ``Component config`` > ``Legacy Driver Configurations`` > ``Legacy I2C Driver Configurations`` > ``Suppress legacy driver deprecated warning``。
|
||||
|
||||
新版 I2C 驱动主要改进了从机和主机的使用方式，详细内容请参考 :ref:`I2C 迁移指南 <migration_guide_i2c_driver_5_2>` 和 :doc:`I2C 驱动编程指南 <../../../api-reference/peripherals/i2c>`。
|
||||
|
||||
I2C 从机驱动更新
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
I2C 从机驱动在 v5.4 上已经被重新设计。在当前版本上，旧的 I2C 从机驱动已经被移除。
|
||||
|
||||
主要概念更新
|
||||
~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^
|
||||
|
||||
- 老版本的 I2C 从机驱动是主动读写，这不符合 I2C 从机的一般用法。在新版的 I2C 从机中，I2C 的读写通过主机驱动产生的事件以触发回调被动完成。
|
||||
- 旧版本的 I2C 从机驱动是主动读写，这不符合 I2C 从机的一般用法。在新版的 I2C 从机中，I2C 的读写通过主机驱动产生的事件以触发回调被动完成。
|
||||
|
||||
主要用法更新
|
||||
~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^
|
||||
|
||||
- ``i2c_slave_receive`` 被移除，在新驱动中使用回调接收数据。
|
||||
- ``i2c_slave_transmit`` 已被 ``i2c_slave_write`` 取代。
|
||||
- ``i2c_slave_write_ram`` 被移除。
|
||||
- ``i2c_slave_read_ram`` 被移除。
|
||||
|
||||
同时，I2C的主机驱动也有一些API用法上的改动
|
||||
I2C 主机驱动更新
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
I2C 主机驱动的 API 也有一些用法上的改动。
|
||||
|
||||
主要用法更新
|
||||
~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^
|
||||
|
||||
当主机在 I2C 总线上检测到 NACK，以下的函数目前会返回 ``ESP_ERR_INVALID_RESPONSE``，而不是像之前一样返回 ``ESP_ERR_INVALID_STATE``：
|
||||
|
||||
- ``i2c_master_transmit``
|
||||
- ``i2c_master_multi_buffer_transmit``
|
||||
- ``i2c_master_transmit_receive``
|
||||
|
||||
@@ -8,7 +8,6 @@
|
||||
#include "sdkconfig.h"
|
||||
#include "esp_wifi.h"
|
||||
|
||||
#include "driver/i2c.h"
|
||||
#include "driver/i2c.h"
|
||||
#include "driver/spi_master.h"
|
||||
#include "driver/spi_common.h"
|
||||
|
||||
@@ -1 +1,3 @@
|
||||
CONFIG_IDF_TARGET="linux"
|
||||
|
||||
CONFIG_I2C_SUPPRESS_DEPRECATE_WARN=y
|
||||
|
||||
Reference in New Issue
Block a user