refactor(rmt): deprecate io_loop_back

when initialize the GPIO for RMT peripehral, driver won't overwrite the
previous GPIO settings. Just append different modes to the GPIO.

components/esp_driver_gpio/README.md

@@ -1,6 +1,6 @@
 # GPIO API usage in Peripheral Drivers
 
-When a peripheral driver initializes IOs, the general rule is to append necessary configurations onto the IO, instead of using any GPIO APIs that overwrite the current IO setting, such as `gpio_config`, `gpio_set_direction`, `gpio_set_pull_mode`.
+When a peripheral driver initializes IOs, the general rule is to append necessary configurations onto the IO, instead of using any GPIO APIs that overwrite the current IO setting, such as `gpio_config`, `gpio_reset_pin`, `gpio_set_direction`, `gpio_set_pull_mode`.
 
 Use `gpio_pullup_en` and `gpio_pulldown_en` to enable the internal pull-up/pull-down resistors if necessary.
 

components/esp_driver_rmt/src/rmt_rx.c

@@ -152,7 +152,11 @@ static void rmt_rx_unregister_from_group(rmt_channel_t *channel, rmt_group_t *gr
 static esp_err_t rmt_rx_destroy(rmt_rx_channel_t *rx_channel)
 {
     if (rx_channel->base.gpio_num >= 0) {
-        gpio_reset_pin(rx_channel->base.gpio_num);
+        int group_id = rx_channel->base.group->group_id;
+        int channel_id = rx_channel->base.channel_id;
+        esp_rom_gpio_connect_in_signal(GPIO_MATRIX_CONST_ZERO_INPUT,
+                                       rmt_periph_signals.groups[group_id].channels[channel_id + RMT_RX_CHANNEL_OFFSET_IN_GROUP].rx_sig,
+                                       false);
     }
     if (rx_channel->base.intr) {
         ESP_RETURN_ON_ERROR(esp_intr_free(rx_channel->base.intr), TAG, "delete interrupt service failed");
@@ -303,20 +307,18 @@ esp_err_t rmt_new_rx_channel(const rmt_rx_channel_config_t *config, rmt_channel_
 #endif
 
     // GPIO Matrix/MUX configuration
-    gpio_config_t gpio_conf = {
-        .intr_type = GPIO_INTR_DISABLE,
-        // also enable the input path is `io_loop_back` is on, this is useful for debug
-        .mode = GPIO_MODE_INPUT | (config->flags.io_loop_back ? GPIO_MODE_OUTPUT : 0),
-        .pull_down_en = false,
-        .pull_up_en = true,
-        .pin_bit_mask = BIT64(config->gpio_num),
-    };
-    // gpio_config also connects the IO_MUX to the GPIO matrix
-    ESP_GOTO_ON_ERROR(gpio_config(&gpio_conf), err, TAG, "config GPIO failed");
-    rx_channel->base.gpio_num = config->gpio_num;
+    gpio_func_sel(config->gpio_num, PIN_FUNC_GPIO);
+    gpio_input_enable(config->gpio_num);
+    gpio_pullup_en(config->gpio_num);
     esp_rom_gpio_connect_in_signal(config->gpio_num,
                                    rmt_periph_signals.groups[group_id].channels[channel_id + RMT_RX_CHANNEL_OFFSET_IN_GROUP].rx_sig,
                                    config->flags.invert_in);
+    rx_channel->base.gpio_num = config->gpio_num;
+
+    // deprecated, to be removed in in esp-idf v6.0
+    if (config->flags.io_loop_back) {
+        gpio_ll_output_enable(&GPIO, config->gpio_num);
+    }
 
     // initialize other members of rx channel
     portMUX_INITIALIZE(&rx_channel->base.spinlock);

components/esp_driver_rmt/src/rmt_tx.c

@@ -212,7 +212,7 @@ exit:
 static esp_err_t rmt_tx_destroy(rmt_tx_channel_t *tx_channel)
 {
     if (tx_channel->base.gpio_num >= 0) {
-        gpio_reset_pin(tx_channel->base.gpio_num);
+        gpio_output_disable(tx_channel->base.gpio_num);
         esp_gpio_revoke(BIT64(tx_channel->base.gpio_num));
     }
     if (tx_channel->base.intr) {
@@ -352,27 +352,28 @@ esp_err_t rmt_new_tx_channel(const rmt_tx_channel_config_t *config, rmt_channel_
     // always enable tx wrap, both DMA mode and ping-pong mode rely this feature
     rmt_ll_tx_enable_wrap(hal->regs, channel_id, true);
 
-    // GPIO Matrix/MUX configuration
-    gpio_config_t gpio_conf = {
-        .intr_type = GPIO_INTR_DISABLE,
-        // also enable the input path if `io_loop_back` is on, this is useful for bi-directional buses
-        .mode = (config->flags.io_od_mode ? GPIO_MODE_OUTPUT_OD : GPIO_MODE_OUTPUT) | (config->flags.io_loop_back ? GPIO_MODE_INPUT : 0),
-        .pull_down_en = false,
-        .pull_up_en = true,
-        .pin_bit_mask = BIT64(config->gpio_num),
-    };
-    ESP_GOTO_ON_ERROR(gpio_config(&gpio_conf), err, TAG, "config GPIO failed");
     // reserve the GPIO output path, because we don't expect another peripheral to signal to the same GPIO
     uint64_t old_gpio_rsv_mask = esp_gpio_reserve(BIT64(config->gpio_num));
     // check if the GPIO is already used by others, RMT TX channel only uses the output path of the GPIO
     if (old_gpio_rsv_mask & BIT64(config->gpio_num)) {
         ESP_LOGW(TAG, "GPIO %d is not usable, maybe conflict with others", config->gpio_num);
     }
+    // GPIO Matrix/MUX configuration
+    gpio_func_sel(config->gpio_num, PIN_FUNC_GPIO);
+    // connect the signal to the GPIO by matrix, it will also enable the output path properly
     esp_rom_gpio_connect_out_signal(config->gpio_num,
                                     rmt_periph_signals.groups[group_id].channels[channel_id + RMT_TX_CHANNEL_OFFSET_IN_GROUP].tx_sig,
                                     config->flags.invert_out, false);
     tx_channel->base.gpio_num = config->gpio_num;
 
+    // deprecated, to be removed in in esp-idf v6.0
+    if (config->flags.io_loop_back) {
+        gpio_ll_input_enable(&GPIO, config->gpio_num);
+    }
+    if (config->flags.io_od_mode) {
+        gpio_ll_od_enable(&GPIO, config->gpio_num);
+    }
+
     portMUX_INITIALIZE(&tx_channel->base.spinlock);
     atomic_init(&tx_channel->base.fsm, RMT_FSM_INIT);
     tx_channel->base.direction = RMT_CHANNEL_DIRECTION_TX;

components/esp_driver_rmt/test_apps/rmt/main/test_rmt_common.c

@@ -132,7 +132,6 @@ TEST_CASE("RMT interrupt priority", "[rmt]")
         .resolution_hz = 1000000, // 1MHz, 1 tick = 1us
         .gpio_num = 0,
         .flags.with_dma = false,    // Interrupt will only be allocated when dma disabled
-        .flags.io_loop_back = true, // the GPIO will act like a loopback
         .intr_priority = 3,
     };
     // --- Check if specifying interrupt priority works

components/esp_driver_rmt/test_apps/rmt/main/test_rmt_iram.c

@@ -135,13 +135,18 @@ static void test_rmt_rx_iram_safe(size_t mem_block_symbols, bool with_dma, rmt_c
                                                                MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL | MALLOC_CAP_DMA);
     TEST_ASSERT_NOT_NULL(remote_codes);
 
+    gpio_config_t sig_simulator_io_conf = {
+        .mode = GPIO_MODE_OUTPUT,
+        .pin_bit_mask = 1ULL << TEST_RMT_GPIO_NUM_A,
+    };
+    TEST_ESP_OK(gpio_config(&sig_simulator_io_conf));
+
     rmt_rx_channel_config_t rx_channel_cfg = {
         .clk_src = clk_src,
         .resolution_hz = 1000000, // 1MHz, 1 tick = 1us
         .mem_block_symbols = mem_block_symbols,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
         .flags.with_dma = with_dma,
-        .flags.io_loop_back = true, // the GPIO will act like a loopback
     };
     printf("install rx channel\r\n");
     rmt_channel_handle_t rx_channel = NULL;

components/esp_driver_rmt/test_apps/rmt/main/test_rmt_rx.c

@@ -55,7 +55,6 @@ static void test_rmt_rx_nec_carrier(size_t mem_block_symbols, bool with_dma, rmt
         .mem_block_symbols = mem_block_symbols,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
         .flags.with_dma = with_dma,
-        .flags.io_loop_back = true, // the GPIO will act like a loopback
     };
     printf("install rx channel\r\n");
     rmt_channel_handle_t rx_channel = NULL;
@@ -75,7 +74,6 @@ static void test_rmt_rx_nec_carrier(size_t mem_block_symbols, bool with_dma, rmt
         .mem_block_symbols = SOC_RMT_MEM_WORDS_PER_CHANNEL,
         .trans_queue_depth = 4,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
-        .flags.io_loop_back = true, // TX channel and RX channel will bounded to the same GPIO
     };
     printf("install tx channel\r\n");
     rmt_channel_handle_t tx_channel = NULL;
@@ -240,13 +238,18 @@ static void test_rmt_partial_receive(size_t mem_block_symbols, bool with_dma, rm
                                                                    MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL | MALLOC_CAP_DMA);
     TEST_ASSERT_NOT_NULL(receive_user_buf);
 
+    gpio_config_t sig_simulator_io_conf = {
+        .mode = GPIO_MODE_OUTPUT,
+        .pin_bit_mask = 1ULL << TEST_RMT_GPIO_NUM_A,
+    };
+    TEST_ESP_OK(gpio_config(&sig_simulator_io_conf));
+
     rmt_rx_channel_config_t rx_channel_cfg = {
         .clk_src = clk_src,
         .resolution_hz = 1000000, // 1MHz, 1 tick = 1us
         .mem_block_symbols = mem_block_symbols,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
         .flags.with_dma = with_dma,
-        .flags.io_loop_back = true, // the GPIO will act like a loopback
     };
     printf("install rx channel\r\n");
     rmt_channel_handle_t rx_channel = NULL;
@@ -332,7 +335,6 @@ static void test_rmt_receive_filter(rmt_clock_source_t clk_src)
         .resolution_hz = 1000000, // 1MHz, 1 tick = 1us
         .mem_block_symbols = SOC_RMT_MEM_WORDS_PER_CHANNEL,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
-        .flags.io_loop_back = true, // the GPIO will act like a loopback
     };
     printf("install rx channel\r\n");
     rmt_channel_handle_t rx_channel = NULL;
@@ -355,7 +357,6 @@ static void test_rmt_receive_filter(rmt_clock_source_t clk_src)
         .mem_block_symbols = SOC_RMT_MEM_WORDS_PER_CHANNEL,
         .trans_queue_depth = 4,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
-        .flags.io_loop_back = true, // TX channel and RX channel will bounded to the same GPIO
     };
     printf("install tx channel\r\n");
     rmt_channel_handle_t tx_channel = NULL;

components/esp_driver_rmt/test_apps/rmt/main/test_rmt_sleep.c

@@ -56,7 +56,6 @@ static void test_rmt_tx_rx_sleep_retention(bool allow_pd)
         .resolution_hz = 1000000,
         .mem_block_symbols = SOC_RMT_MEM_WORDS_PER_CHANNEL,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
-        .flags.io_loop_back = true,
         .flags.allow_pd = allow_pd,
     };
     printf("install rx channel\r\n");
@@ -77,7 +76,6 @@ static void test_rmt_tx_rx_sleep_retention(bool allow_pd)
         .mem_block_symbols = SOC_RMT_MEM_WORDS_PER_CHANNEL,
         .trans_queue_depth = 4,
         .gpio_num = TEST_RMT_GPIO_NUM_A,
-        .flags.io_loop_back = true,
         .flags.allow_pd = allow_pd,
     };
     printf("install tx channel\r\n");
@@ -111,7 +109,7 @@ static void test_rmt_tx_rx_sleep_retention(bool allow_pd)
     TEST_ASSERT_EQUAL(0, sleep_ctx.sleep_request_result);
 #if SOC_RMT_SUPPORT_SLEEP_RETENTION
     // check if the power domain also is powered down
-    TEST_ASSERT_EQUAL(back_up_before_sleep ? PMU_SLEEP_PD_TOP : 0, (sleep_ctx.sleep_flags) & PMU_SLEEP_PD_TOP);
+    TEST_ASSERT_EQUAL(allow_pd ? PMU_SLEEP_PD_TOP : 0, (sleep_ctx.sleep_flags) & PMU_SLEEP_PD_TOP);
 #endif
     esp_sleep_set_sleep_context(NULL);
 

docs/en/api-reference/peripherals/rmt.rst

@@ -90,8 +90,6 @@ To install an RMT TX channel, there is a configuration structure that needs to b
 - :cpp:member:`rmt_tx_channel_config_t::trans_queue_depth` sets the depth of the internal transaction queue, the deeper the queue, the more transactions can be prepared in the backlog.
 - :cpp:member:`rmt_tx_channel_config_t::invert_out` is used to decide whether to invert the RMT signal before sending it to the GPIO pad.
 - :cpp:member:`rmt_tx_channel_config_t::with_dma` enables the DMA backend for the channel. Using the DMA allows a significant amount of the channel's workload to be offloaded from the CPU. However, the DMA backend is not available on all ESP chips, please refer to [`TRM <{IDF_TARGET_TRM_EN_URL}#rmt>`__] before you enable this option. Or you might encounter a :c:macro:`ESP_ERR_NOT_SUPPORTED` error.
-- :cpp:member:`rmt_tx_channel_config_t::io_loop_back` enables both input and output capabilities on the channel's assigned GPIO. Thus, by binding a TX and RX channel to the same GPIO, loopback can be achieved.
-- :cpp:member:`rmt_tx_channel_config_t::io_od_mode` configures the channel's assigned GPIO as open-drain. When combined with :cpp:member:`rmt_tx_channel_config_t::io_loop_back`, a bi-directional bus (e.g., 1-wire) can be achieved.
 - :cpp:member:`rmt_tx_channel_config_t::intr_priority` Set 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:`rmt_tx_channel_config_t::intr_priority`. Please use the number form (1,2,3) , not 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:`rmt_del_channel` is called.
 - :cpp:member:`rmt_tx_channel_config_t::allow_pd` configures if the driver allows the system to power down the peripheral in light sleep mode. Before entering sleep, the system will backup the RMT register context, which will be restored later when the system exit the sleep mode. Powering down the peripheral can save more power, but at the cost of more memory consumed to save the register context. It's a tradeoff between power consumption and memory consumption. This configuration option relies on specific hardware feature, if you enable it on an unsupported chip, you will see error message like ``not able to power down in light sleep``.
 
@@ -126,7 +124,6 @@ To install an RMT RX channel, there is a configuration structure that needs to b
 
 - :cpp:member:`rmt_rx_channel_config_t::invert_in` is used to invert the input signals before it is passed to the RMT receiver. The inversion is done by the GPIO matrix instead of by the RMT peripheral.
 - :cpp:member:`rmt_rx_channel_config_t::with_dma` enables the DMA backend for the channel. Using the DMA allows a significant amount of the channel's workload to be offloaded from the CPU. However, the DMA backend is not available on all ESP chips, please refer to [`TRM <{IDF_TARGET_TRM_EN_URL}#rmt>`__] before you enable this option. Or you might encounter a :c:macro:`ESP_ERR_NOT_SUPPORTED` error.
-- :cpp:member:`rmt_rx_channel_config_t::io_loop_back` enables both input and output capabilities on the channel's assigned GPIO. Thus, by binding a TX and RX channel to the same GPIO, loopback can be achieved.
 - :cpp:member:`rmt_rx_channel_config_t::intr_priority` Set 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:`rmt_rx_channel_config_t::intr_priority`. Please use the number form (1,2,3) , not 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:`rmt_del_channel` is called.
 - :cpp:member:`rmt_rx_channel_config_t::allow_pd` configures if the driver allows the system to power down the peripheral in light sleep mode. Before entering sleep, the system will backup the RMT register context, which will be restored later when the system exit the sleep mode. Powering down the peripheral can save more power, but at the cost of more memory consumed to save the register context. It's a tradeoff between power consumption and memory consumption. This configuration option relies on specific hardware feature, if you enable it on an unsupported chip, you will see error message like ``not able to power down in light sleep``.
 

docs/zh_CN/api-reference/peripherals/rmt.rst

@@ -90,8 +90,6 @@ RMT 接收器可以对输入信号采样，将其转换为 RMT 数据格式，
 - :cpp:member:`rmt_tx_channel_config_t::trans_queue_depth` 设置内部事务队列深度。队列越深，在待处理队列中可以准备的事务越多。
 - :cpp:member:`rmt_tx_channel_config_t::invert_out` 决定是否在将 RMT 信号发送到 GPIO 管脚前反转 RMT 信号。
 - :cpp:member:`rmt_tx_channel_config_t::with_dma` 为通道启用 DMA 后端。启用 DMA 后端可以释放 CPU 上的大部分通道工作负载，显著减轻 CPU 负担。但并非所有 ESP 芯片都支持 DMA 后端，在启用此选项前，请参阅 [`TRM <{IDF_TARGET_TRM_EN_URL}#rmt>`__]。若所选芯片不支持 DMA 后端，可能会报告 :c:macro:`ESP_ERR_NOT_SUPPORTED` 错误。
-- :cpp:member:`rmt_tx_channel_config_t::io_loop_back` 启用通道所分配的 GPIO 上的输入和输出功能，将发送通道和接收通道绑定到同一个 GPIO 上，从而实现回环功能。
-- :cpp:member:`rmt_tx_channel_config_t::io_od_mode` 配置通道分配的 GPIO 为开漏模式 (open-drain)。当与 :cpp:member:`rmt_tx_channel_config_t::io_loop_back` 结合使用时，可以实现双向总线，如 1-wire。
 - :cpp:member:`rmt_tx_channel_config_t::intr_priority` 设置中断的优先级。如果设置为 ``0`` ，驱动将会使用一个中低优先级的中断（优先级可能为 1，2 或 3），否则会使用 :cpp:member:`rmt_tx_channel_config_t::intr_priority` 指定的优先级。请使用优先级序号 (1, 2, 3)，而不是 bitmask 的形式（(1<<1)，(1<<2)，(1<<3)）。请注意，中断优先级一旦设置，在 :cpp:func:`rmt_del_channel` 被调用之前不可再次修改。
 - :cpp:member:`rmt_tx_channel_config_t::allow_pd` 配置驱动程序是否允许系统在睡眠模式下关闭外设电源。在进入睡眠之前，系统将备份 RMT 寄存器上下文，当系统退出睡眠模式时，这些上下文将被恢复。关闭外设可以节省更多功耗，但代价是消耗更多内存来保存寄存器上下文。你需要在功耗和内存消耗之间做权衡。此配置选项依赖于特定的硬件功能，如果在不支持的芯片上启用它，你将看到类似 ``not able to power down in light sleep`` 的错误消息。
 
@@ -126,7 +124,6 @@ RMT 接收器可以对输入信号采样，将其转换为 RMT 数据格式，
 
 - :cpp:member:`rmt_rx_channel_config_t::invert_in` 在输入信号传递到 RMT 接收器前对其进行反转。该反转由 GPIO 交换矩阵完成，而非 RMT 外设。
 - :cpp:member:`rmt_rx_channel_config_t::with_dma` 为通道启用 DMA 后端。启用 DMA 后端可以释放 CPU 上的大部分通道工作负载，显著减轻 CPU 负担。但并非所有 ESP 芯片都支持 DMA 后端，在启用此选项前，请参阅 [`TRM <{IDF_TARGET_TRM_EN_URL}#rmt>`__]。若所选芯片不支持 DMA 后端，可能会报告 :c:macro:`ESP_ERR_NOT_SUPPORTED` 错误。
-- :cpp:member:`rmt_rx_channel_config_t::io_loop_back` 启用通道所分配的 GPIO 上的输入和输出功能，将发送通道和接收通道绑定到同一个 GPIO 上，从而实现回环功能。
 - :cpp:member:`rmt_rx_channel_config_t::intr_priority` 设置中断的优先级。如果设置为 ``0`` ，驱动将会使用一个中低优先级的中断（优先级可能为 1，2 或 3），否则会使用 :cpp:member:`rmt_rx_channel_config_t::intr_priority` 指定的优先级。请使用优先级序号 (1，2，3)，而不是 bitmask 的形式（(1<<1)，(1<<2)，(1<<3)）。请注意，中断优先级一旦设置，在 :cpp:func:`rmt_del_channel` 被调用之前不可再次修改。
 - :cpp:member:`rmt_rx_channel_config_t::allow_pd` 配置驱动程序是否允许系统在睡眠模式下关闭外设电源。在进入睡眠之前，系统将备份 RMT 寄存器上下文，当系统退出睡眠模式时，这些上下文将被恢复。关闭外设可以节省更多功耗，但代价是消耗更多内存来保存寄存器上下文。你需要在功耗和内存消耗之间做权衡。此配置选项依赖于特定的硬件功能，如果在不支持的芯片上启用它，你将看到类似 ``not able to power down in light sleep`` 的错误消息。
 

tools/unit-test-app/components/test_utils/ref_clock_impl_rmt_pcnt.c

@@ -51,7 +51,6 @@ void ref_clock_init(void)
     pcnt_chan_config_t chan_config = {
         .edge_gpio_num = REF_CLOCK_GPIO,
         .level_gpio_num = -1,
-        .flags.io_loop_back = true,
     };
     TEST_ESP_OK(pcnt_new_channel(s_pcnt_unit, &chan_config, &s_pcnt_chan));
     // increase count on both edges
@@ -72,7 +71,6 @@ void ref_clock_init(void)
         .mem_block_symbols = 64,
         .resolution_hz = 10000, // channel resolution doesn't really matter, because we only utilize the carrier
         .trans_queue_depth = 1,
-        .flags.io_loop_back = true,
     };
     TEST_ESP_OK(rmt_new_tx_channel(&tx_chan_config, &s_rmt_chan));
     // set carrier configuration