refactor(i2s): replace the enum i2s_port_t with int type

2025-10-14 02:08:21 +08:00 · 2025-09-23 12:27:48 +08:00
parent 91a6387005
commit fec96035be
22 changed files with 36 additions and 37 deletions
--- a/components/esp_driver_i2s/i2s_common.c
+++ b/components/esp_driver_i2s/i2s_common.c
@@ -23,6 +23,7 @@

 #include "soc/i2s_periph.h"
 #include "soc/soc_caps.h"
+#include "soc/soc_caps_full.h"
 #include "hal/i2s_hal.h"
 #include "hal/hal_utils.h"
 #include "hal/dma_types.h"
@@ -753,7 +754,7 @@ static void i2s_dma_tx_callback(void *arg)
 esp_err_t i2s_init_dma_intr(i2s_chan_handle_t handle, int intr_flag)
 {
    esp_err_t ret = ESP_OK;
-    i2s_port_t port_id = handle->controller->id;
+    int port_id = handle->controller->id;
    ESP_RETURN_ON_FALSE((port_id >= 0) && (port_id < SOC_I2S_ATTR(INST_NUM)), ESP_ERR_INVALID_ARG, TAG, "invalid handle");
    /* Set GDMA trigger module */
    gdma_trigger_t trig = {.periph = GDMA_TRIG_PERIPH_I2S};
@@ -824,7 +825,7 @@ err1:
 esp_err_t i2s_init_dma_intr(i2s_chan_handle_t handle, int intr_flag)
 {
    esp_err_t ret = ESP_OK;
-    i2s_port_t port_id = handle->controller->id;
+    int port_id = handle->controller->id;
    ESP_RETURN_ON_FALSE((port_id >= 0) && (port_id < SOC_I2S_ATTR(INST_NUM)), ESP_ERR_INVALID_ARG, TAG, "invalid handle");
    intr_flag |= handle->intr_prio_flags;
    /* Initialize I2S module interrupt */
@@ -906,7 +907,7 @@ void i2s_gpio_loopback_set(i2s_chan_handle_t handle, int gpio, uint32_t out_sig_
    }
 }

-esp_err_t i2s_check_set_mclk(i2s_chan_handle_t handle, i2s_port_t id, int gpio_num, i2s_clock_src_t clk_src, bool is_invert)
+esp_err_t i2s_check_set_mclk(i2s_chan_handle_t handle, int id, int gpio_num, i2s_clock_src_t clk_src, bool is_invert)
 {
    if (gpio_num == (int)I2S_GPIO_UNUSED) {
        return ESP_OK;
@@ -947,16 +948,16 @@ esp_err_t i2s_new_channel(const i2s_chan_config_t *chan_cfg, i2s_chan_handle_t *
    /* Parameter validity check */
    I2S_NULL_POINTER_CHECK(TAG, chan_cfg);
    I2S_NULL_POINTER_CHECK(TAG, tx_handle || rx_handle);
-    ESP_RETURN_ON_FALSE(chan_cfg->id < SOC_I2S_ATTR(INST_NUM) || chan_cfg->id == I2S_NUM_AUTO, ESP_ERR_INVALID_ARG, TAG, "invalid I2S port id");
+    ESP_RETURN_ON_FALSE((chan_cfg->id >= 0 && chan_cfg->id < SOC_I2S_ATTR(INST_NUM)) || chan_cfg->id == I2S_NUM_AUTO, ESP_ERR_INVALID_ARG, TAG, "invalid I2S port id");
    ESP_RETURN_ON_FALSE(chan_cfg->dma_desc_num >= 2, ESP_ERR_INVALID_ARG, TAG, "there should be at least 2 DMA buffers");
    ESP_RETURN_ON_FALSE(chan_cfg->intr_priority >= 0 && chan_cfg->intr_priority <= 7, ESP_ERR_INVALID_ARG, TAG, "intr_priority should be within 0~7");
-#if !SOC_MODULE_SUPPORT(I2S, SLEEP_RETENTION)
+#if !SOC_HAS(PAU)
    ESP_RETURN_ON_FALSE(!chan_cfg->allow_pd, ESP_ERR_NOT_SUPPORTED, TAG, "register back up is not supported");
 #endif

    esp_err_t ret = ESP_OK;
    i2s_controller_t *i2s_obj = NULL;
-    i2s_port_t id = chan_cfg->id;
+    int id = chan_cfg->id;
    bool channel_found = false;
    uint8_t chan_search_mask = 0;
    chan_search_mask |= tx_handle ? I2S_DIR_TX : 0;
--- a/components/esp_driver_i2s/i2s_private.h
+++ b/components/esp_driver_i2s/i2s_private.h
@@ -13,6 +13,7 @@
 #include "freertos/queue.h"
 #include "soc/lldesc.h"
 #include "soc/soc_caps.h"
+#include "soc/soc_caps_full.h"
 #include "hal/i2s_hal.h"
 #include "hal/lp_i2s_hal.h"
 #if SOC_LP_I2S_SUPPORTED
@@ -61,7 +62,7 @@ extern "C" {
 #define I2S_RCC_ATOMIC()
 #endif

-#define I2S_USE_RETENTION_LINK  (SOC_MODULE_SUPPORT(I2S, SLEEP_RETENTION) && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP)
+#define I2S_USE_RETENTION_LINK  (SOC_HAS(PAU) && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP)

 #define I2S_NULL_POINTER_CHECK(tag, p)          ESP_RETURN_ON_FALSE((p), ESP_ERR_INVALID_ARG, tag, "input parameter '"#p"' is NULL")
 #define MAX(a, b) ((a) > (b) ? (a) : (b))
@@ -131,7 +132,7 @@ typedef struct {
 * @note  Both i2s rx and tx channel are under its control
 */
 typedef struct {
-    i2s_port_t              id;             /*!< i2s port id */
+    int                     id;             /*!< i2s port id */
    i2s_hal_context_t       hal;            /*!< hal context */
    uint32_t                chan_occupancy; /*!< channel occupancy (rx/tx) */
    bool                    full_duplex;    /*!< is full_duplex */
@@ -312,7 +313,7 @@ void i2s_gpio_check_and_set(i2s_chan_handle_t handle, int gpio, uint32_t signal_
 *      - ESP_OK                Set mclk output gpio success
 *      - ESP_ERR_INVALID_ARG   Invalid GPIO number
 */
-esp_err_t i2s_check_set_mclk(i2s_chan_handle_t handle, i2s_port_t id, int gpio_num, i2s_clock_src_t clk_src, bool is_invert);
+esp_err_t i2s_check_set_mclk(i2s_chan_handle_t handle, int id, int gpio_num, i2s_clock_src_t clk_src, bool is_invert);

 /**
 * @brief Attach data out signal and data in signal to a same gpio
--- a/components/esp_driver_i2s/include/driver/i2s_common.h
+++ b/components/esp_driver_i2s/include/driver/i2s_common.h
@@ -57,7 +57,7 @@ typedef struct {
 * @brief I2S controller channel configuration
 */
 typedef struct {
-    i2s_port_t          id;                 /*!< I2S port id */
+    int                 id;                 /*!< I2S port id */
    i2s_role_t          role;               /*!< I2S role, I2S_ROLE_MASTER or I2S_ROLE_SLAVE */

    /* DMA configurations */
@@ -85,7 +85,7 @@ typedef struct {
 * @brief I2S channel information
 */
 typedef struct {
-    i2s_port_t          id;                 /*!< I2S port id */
+    int                 id;                 /*!< I2S port id */
    i2s_role_t          role;               /*!< I2S role, I2S_ROLE_MASTER or I2S_ROLE_SLAVE */
    i2s_dir_t           dir;                /*!< I2S channel direction */
    i2s_comm_mode_t     mode;               /*!< I2S channel communication mode */
--- a/components/esp_driver_i2s/include/driver/i2s_types.h
+++ b/components/esp_driver_i2s/include/driver/i2s_types.h
@@ -15,15 +15,10 @@
 extern "C" {
 #endif

-/**
- * @brief I2S controller port number, see the _SOC_CAPS_I2S_INST_NUM for the max port number.
- */
-typedef enum {
-    I2S_NUM_0 = 0,                 /*!< I2S controller port 0 */
-    I2S_NUM_1 = 1,                 /*!< I2S controller port 1 */
-    I2S_NUM_2 = 2,                 /*!< I2S controller port 2 */
-    I2S_NUM_AUTO,                  /*!< Select whichever port is available */
-} i2s_port_t;
+#define I2S_NUM_0           0       /*!< I2S controller port 0 */
+#define I2S_NUM_1           1       /*!< I2S controller port 1 */
+#define I2S_NUM_2           2       /*!< I2S controller port 2 */
+#define I2S_NUM_AUTO        -1      /*!< Select an available port automatically */

 /**
 * @brief I2S controller communication mode
--- a/components/esp_driver_i2s/test_apps/i2s/main/test_i2s_sleep.c
+++ b/components/esp_driver_i2s/test_apps/i2s/main/test_i2s_sleep.c
@@ -13,13 +13,14 @@
 #include "driver/i2s_std.h"
 #include "driver/uart.h"
 #include "soc/i2s_struct.h"
+#include "soc/soc_caps_full.h"
 #include "esp_sleep.h"
 #include "esp_private/sleep_cpu.h"
 #include "esp_private/esp_sleep_internal.h"
 #include "esp_private/esp_pmu.h"
 #include "../../test_inc/test_i2s.h"

-#define TEST_I2S_PD_SLEEP   (SOC_MODULE_SUPPORT(I2S, SLEEP_RETENTION) && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP)
+#define TEST_I2S_PD_SLEEP   (SOC_HAS(PAU) && CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP)

 extern void i2s_read_write_test(i2s_chan_handle_t tx_chan, i2s_chan_handle_t rx_chan);

--- a/components/esp_hw_support/sleep_system_peripheral.c
+++ b/components/esp_hw_support/sleep_system_peripheral.c
@@ -239,13 +239,13 @@ bool peripheral_domain_pd_allowed(void)

 #if SOC_HAS(PAU)
    mask.bitmap[SLEEP_RETENTION_MODULE_I2S0 >> 5] |= BIT(SLEEP_RETENTION_MODULE_I2S0 % 32);
-# if (SOC_I2S_ATTR(INST_NUM) > 1)
+# if (SOC_MODULE_ATTR(I2S, INST_NUM) > 1)
    mask.bitmap[SLEEP_RETENTION_MODULE_I2S1 >> 5] |= BIT(SLEEP_RETENTION_MODULE_I2S1 % 32);
 # endif
-# if (SOC_I2S_ATTR(INST_NUM) > 2)
+# if (SOC_MODULE_ATTR(I2S, INST_NUM) > 2)
    mask.bitmap[SLEEP_RETENTION_MODULE_I2S2 >> 5] |= BIT(SLEEP_RETENTION_MODULE_I2S2 % 32);
 # endif
-#endif /* SOC_MODULE_SUPPORT(I2S, SLEEP_RETENTION) */
+#endif /* SOC_HAS(PAU) */

 #if SOC_I2C_SUPPORT_SLEEP_RETENTION
    mask.bitmap[SLEEP_RETENTION_MODULE_I2C0 >> 5] |= BIT(SLEEP_RETENTION_MODULE_I2C0 % 32);
--- a/components/soc/esp32/include/soc/soc_caps_full.h
+++ b/components/soc/esp32/include/soc/soc_caps_full.h
@@ -32,7 +32,6 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    2  // Number of I2S instances
 #define _SOC_CAPS_I2S_MAX_DATA_WIDTH              24 // Maximum data line width of I2S
 #define _SOC_CAPS_I2S_TRANS_SIZE_ALIGN_WORD       1  // I2S DMA transfer size must be aligned to word
--- a/components/soc/esp32c3/include/soc/soc_caps_full.h
+++ b/components/soc/esp32c3/include/soc/soc_caps_full.h
@@ -30,5 +30,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
--- a/components/soc/esp32c5/include/soc/soc_caps_full.h
+++ b/components/soc/esp32c5/include/soc/soc_caps_full.h
@@ -40,5 +40,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
--- a/components/soc/esp32c6/include/soc/soc_caps_full.h
+++ b/components/soc/esp32c6/include/soc/soc_caps_full.h
@@ -40,5 +40,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
--- a/components/soc/esp32c61/include/soc/soc_caps_full.h
+++ b/components/soc/esp32c61/include/soc/soc_caps_full.h
@@ -30,5 +30,4 @@

 /*--------------------------- I2S CAPS ----------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
--- a/components/soc/esp32h2/include/soc/soc_caps_full.h
+++ b/components/soc/esp32h2/include/soc/soc_caps_full.h
@@ -40,5 +40,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
--- a/components/soc/esp32h21/include/soc/soc_caps_full.h
+++ b/components/soc/esp32h21/include/soc/soc_caps_full.h
@@ -36,5 +36,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-// #define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 // #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
--- a/components/soc/esp32h4/include/soc/soc_caps_full.h
+++ b/components/soc/esp32h4/include/soc/soc_caps_full.h
@@ -36,5 +36,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
--- a/components/soc/esp32p4/include/soc/soc_caps_full.h
+++ b/components/soc/esp32p4/include/soc/soc_caps_full.h
@@ -43,5 +43,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    3  // Number of I2S instances
--- a/components/soc/esp32s2/include/soc/soc_caps_full.h
+++ b/components/soc/esp32s2/include/soc/soc_caps_full.h
@@ -36,7 +36,6 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    1  // Number of I2S instances
 #define _SOC_CAPS_I2S_MAX_DATA_WIDTH              24
 #define _SOC_CAPS_I2S_SUPPORT_DMA_EQUAL           1
--- a/components/soc/esp32s3/include/soc/soc_caps_full.h
+++ b/components/soc/esp32s3/include/soc/soc_caps_full.h
@@ -36,5 +36,4 @@

 /*------------------------------- I2S ---------------------------------------*/
 // helper macros to access module attributes
-#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
 #define _SOC_CAPS_I2S_INST_NUM                    2  // Number of I2S instances
--- a/components/soc/include/soc/i2s_periph.h
+++ b/components/soc/include/soc/i2s_periph.h
@@ -19,6 +19,8 @@
 #include "soc/i2s_reg.h"
 #endif

+#define SOC_I2S_ATTR(_attr)                       SOC_MODULE_ATTR(I2S, _attr)
+
 #ifdef __cplusplus
 extern "C" {
 #endif
--- a/docs/en/migration-guides/release-5.x/5.0/peripherals.rst
+++ b/docs/en/migration-guides/release-5.x/5.0/peripherals.rst
@@ -499,7 +499,7 @@ LCD
    - The :cpp:type:`i2s_chan_handle_t` handle type is used to uniquely identify I2S channels. All the APIs require the channel handle and users need to maintain the channel handles by themselves.
    - On the ESP32-C3 and ESP32-S3, TX and RX channels in the same controller can be configured to different clocks or modes.
    - However, on the ESP32 and ESP32-S2, the TX and RX channels of the same controller still share some hardware resources. Thus, configurations may cause one channel to affect another channel in the same controller.
-    - The channels can be registered to an available I2S controller automatically by setting :cpp:enumerator:`i2s_port_t::I2S_NUM_AUTO` as I2S port ID which causes the driver to search for the available TX/RX channels. However, the driver also supports registering channels to a specific port.
+    - The channels can be registered to an available I2S controller automatically by setting ``I2S_NUM_AUTO`` as I2S port ID which causes the driver to search for the available TX/RX channels. However, the driver also supports registering channels to a specific port.
    - In order to distinguish between TX/RX channels and sound channels, the term "channel" in the context of the I2S driver only refers to TX/RX channels. Meanwhile, sound channels are referred to as "slots".

    I2S Mode Categorization
--- a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst
+++ b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst
@@ -264,6 +264,11 @@ Touch Sensor

 The ``touch_sensor_sample_config_t::bypass_shield_output`` member for version 3 touch sensor has been removed because it is not supported in the version 3 hardware.

+I2S
+---
+
+- ``i2s_port_t`` type has been removed. Please use ``int`` type instead. Its enum items ``I2S_NUM_0``, ``I2S_NUM_1``, ``I2S_NUM_2`` and ``I2S_NUM_AUTO`` have been replaced by macro definitions to ensure compatibility.
+
 USB
 ---

--- a/docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst
@@ -499,7 +499,7 @@ LCD
    - :cpp:type:`i2s_chan_handle_t` 句柄类型用于唯一地识别 I2S 通道。所有的 API 都需要该通道句柄，用户需要对这些通道句柄进行维护。
    - 对于 ESP32-C3 和 ESP32-S3，同一个控制器中的发送通道和接收通道可以配置为不同的时钟或不同的模式。
    - 但是对于 ESP32 和 ESP32-S2， 同一个控制器中的发送通道和接收通道共享某些硬件资源。因此，配置可能会造成一个通道影响同一个控制器中的另一个通道。
-    - 通过将 :cpp:enumerator:`i2s_port_t::I2S_NUM_AUTO` 设置为 I2S 端口 ID，驱动会搜索可用的发送/接收通道，之后通道会被自动注册到可用的 I2S 控制器上。但是，驱动仍然支持将通道注册到一个特定的端口上。
+    - 通过将 ``I2S_NUM_AUTO`` 设置为 I2S 端口 ID，驱动会搜索可用的发送/接收通道，之后通道会被自动注册到可用的 I2S 控制器上。但是，驱动仍然支持将通道注册到一个特定的端口上。
    - 为区分发送/接收通道和声音通道，在更新后的驱动中，“通道 (channel)”一词仅代表发送/接收通道，用“声道 (slot)”来表示声音通道。

    I2S 模式分类
--- a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst
+++ b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst
@@ -263,3 +263,8 @@ Touch Sensor
 ------------

 第三版触摸传感器的驱动配置项 ``touch_sensor_sample_config_t::bypass_shield_output`` 已被移除，因为第三版触摸传感器硬件已不支持该功能。
+
+I2S
+---
+
+- ``i2s_port_t`` 类型已被移除。请使用 ``int`` 类型代替。该类型原有的 enum 项 ``I2S_NUM_0``，``I2S_NUM_1``，``I2S_NUM_2`` 和 ``I2S_NUM_AUTO`` 已用宏定义代替，以保证兼容性。