feat(ledc): Add channel deconfiguration option to release the occupied IOs

Closes https://github.com/espressif/esp-idf/issues/15666

components/esp_driver_ledc/include/driver/ledc.h

@@ -45,6 +45,9 @@ typedef struct {
     struct ledc_channel_flags {
         unsigned int output_invert: 1; /*!< Enable (1) or disable (0) gpio output invert */
     } flags;                        /*!< Extra configuration flags for LEDC channel */
+    bool deconfigure;               /*!< Set this field to de-configure a LEDC channel which has been configured before
+                                         The driver only does limited action to release the pins occupied by this channel only.
+                                         When this field is set, gpio_num, timer_sel, duty, hpoint, sleep_mode, flags fields are ignored. */
 } ledc_channel_config_t;
 
 /**

components/esp_driver_ledc/src/ledc.c

@@ -94,6 +94,7 @@ typedef struct {
     bool channel_keep_alive[LEDC_CHANNEL_MAX];          /*!< Records whether each channel needs to keep output during sleep */
     uint8_t timer_xpd_ref_cnt[LEDC_TIMER_MAX];          /*!< Records the timer (glb_clk) not power down during sleep requirement */
     bool glb_clk_xpd;                                   /*!< Records the power strategy applied to the global clock */
+    uint64_t occupied_pin_mask[LEDC_CHANNEL_MAX];       /*!< Records the pins occupied by each channel */
 } ledc_obj_t;
 
 static ledc_obj_t *p_ledc_obj[LEDC_SPEED_MODE_MAX] = {
@@ -805,7 +806,7 @@ esp_err_t ledc_timer_config(const ledc_timer_config_t *timer_conf)
     return ret;
 }
 
-esp_err_t _ledc_set_pin(int gpio_num, bool out_inv, ledc_mode_t speed_mode, ledc_channel_t channel)
+static esp_err_t _ledc_set_pin(int gpio_num, bool out_inv, ledc_mode_t speed_mode, ledc_channel_t channel)
 {
     // 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(gpio_num));
@@ -814,6 +815,9 @@ esp_err_t _ledc_set_pin(int gpio_num, bool out_inv, ledc_mode_t speed_mode, ledc
         ESP_LOGW(LEDC_TAG, "GPIO %d is not usable, maybe conflict with others", gpio_num);
     }
     gpio_matrix_output(gpio_num, ledc_periph_signal[speed_mode].sig_out0_idx + channel, out_inv, false);
+    portENTER_CRITICAL(&ledc_spinlock);
+    p_ledc_obj[speed_mode]->occupied_pin_mask[channel] |= BIT64(gpio_num);
+    portEXIT_CRITICAL(&ledc_spinlock);
     return ESP_OK;
 }
 
@@ -823,9 +827,31 @@ esp_err_t ledc_set_pin(int gpio_num, ledc_mode_t speed_mode, ledc_channel_t chan
     LEDC_ARG_CHECK(channel < LEDC_CHANNEL_MAX, "channel");
     LEDC_ARG_CHECK(speed_mode < LEDC_SPEED_MODE_MAX, "speed_mode");
     LEDC_ARG_CHECK(GPIO_IS_VALID_OUTPUT_GPIO(gpio_num), "gpio_num");
+    LEDC_CHECK(p_ledc_obj[speed_mode] != NULL, LEDC_NOT_INIT, ESP_ERR_INVALID_STATE);
     return _ledc_set_pin(gpio_num, false, speed_mode, channel);
 }
 
+static esp_err_t ledc_channel_del(ledc_mode_t speed_mode, ledc_channel_t channel)
+{
+    LEDC_CHECK(p_ledc_obj[speed_mode] != NULL, LEDC_NOT_INIT, ESP_ERR_INVALID_STATE);
+
+    portENTER_CRITICAL(&ledc_spinlock);
+    // release all the pins occupied by this channel
+    while (p_ledc_obj[speed_mode]->occupied_pin_mask[channel]) {
+        int gpio_num = __builtin_ffsll(p_ledc_obj[speed_mode]->occupied_pin_mask[channel]) - 1;
+        gpio_output_disable(gpio_num);
+        esp_gpio_revoke(BIT64(gpio_num));
+        p_ledc_obj[speed_mode]->occupied_pin_mask[channel] &= ~BIT64(gpio_num);
+    }
+    ledc_ll_enable_channel_power(LEDC_LL_GET_HW(), speed_mode, channel, false);
+    portEXIT_CRITICAL(&ledc_spinlock);
+
+    // p_ledc_obj[speed_mode]->channel_keep_alive[channel] = false;
+    // TODO: dealing whether need to release the timer clock source xpd
+    // TODO: dealing whether can downgrade the sleep mode, so that retention link can be freed or peripheral clock can be gated during sleep
+    return ESP_OK;
+}
+
 esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf)
 {
     LEDC_ARG_CHECK(ledc_conf, "ledc_conf");
@@ -838,6 +864,11 @@ esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf)
     bool output_invert = ledc_conf->flags.output_invert;
     LEDC_ARG_CHECK(ledc_channel < LEDC_CHANNEL_MAX, "ledc_channel");
     LEDC_ARG_CHECK(speed_mode < LEDC_SPEED_MODE_MAX, "speed_mode");
+
+    if (ledc_conf->deconfigure) {
+        return ledc_channel_del(speed_mode, ledc_channel);
+    }
+
     LEDC_ARG_CHECK(GPIO_IS_VALID_OUTPUT_GPIO(gpio_num), "gpio_num");
     LEDC_ARG_CHECK(timer_select < LEDC_TIMER_MAX, "timer_select");
     LEDC_ARG_CHECK(ledc_conf->sleep_mode < LEDC_SLEEP_MODE_INVALID, "sleep_mode");

components/esp_driver_ledc/test_apps/ledc/main/test_app_main.c

@@ -10,8 +10,8 @@
 #include "esp_newlib.h"
 
 // Some resources are lazy allocated in LEDC driver, the threshold is left for that case
-// This leak is large since LEDC driver does not provide channel delete mechanism
+// This leak is large since LEDC driver does not provide context free mechanism
-#define TEST_MEMORY_LEAK_THRESHOLD (500)
+#define TEST_MEMORY_LEAK_THRESHOLD (550)
 
 void setUp(void)
 {

components/esp_driver_ledc/test_apps/ledc/main/test_ledc.c

@@ -36,6 +36,17 @@ static void fade_setup(void)
     TEST_ESP_OK(ledc_fade_func_install(0));
 }
 
+static void fade_teardown(void)
+{
+    ledc_channel_config_t ledc_ch_config = initialize_channel_config();
+
+    // deinitialize fade service
+    ledc_fade_func_uninstall();
+
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
+}
+
 static void timer_duty_set_get(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t duty)
 {
     TEST_ESP_OK(ledc_set_duty(speed_mode, channel, duty));
@@ -67,6 +78,9 @@ static void timer_duty_test(ledc_channel_t channel, ledc_timer_bit_t timer_bit,
     timer_duty_set_get(ledc_ch_config.speed_mode, ledc_ch_config.channel, 1 << (timer_bit - 1)); // 50% duty
     timer_duty_set_get(ledc_ch_config.speed_mode, ledc_ch_config.channel, (1 << timer_bit) - 1);
     timer_duty_set_get(ledc_ch_config.speed_mode, ledc_ch_config.channel, (1 << timer_bit) - 2);
+
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
 }
 
 TEST_CASE("LEDC channel config wrong gpio", "[ledc]")
@@ -100,7 +114,9 @@ TEST_CASE("LEDC wrong timer", "[ledc]")
 TEST_CASE("LEDC channel config basic parameter test", "[ledc]")
 {
     ledc_channel_config_t ledc_ch_config = initialize_channel_config();
-    TEST_ASSERT_EQUAL(ESP_OK, ledc_channel_config(&ledc_ch_config));
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
 }
 
 TEST_CASE("LEDC wrong duty resolution", "[ledc]")
@@ -148,6 +164,9 @@ TEST_CASE("LEDC output idle level test", "[ledc]")
         TEST_ASSERT_EQUAL_INT32(!current_level, gpio_get_level(PULSE_IO));
         esp_rom_delay_us(50);
     }
+
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
 }
 
 TEST_CASE("LEDC iterate over all channel and timer configs", "[ledc]")
@@ -168,6 +187,10 @@ TEST_CASE("LEDC iterate over all channel and timer configs", "[ledc]")
                 ledc_time_config.timer_num = (ledc_timer_t)k;
                 TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
                 TEST_ESP_OK(ledc_timer_config(&ledc_time_config));
+
+                ledc_ch_config.deconfigure = true;
+                TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
+                ledc_ch_config.deconfigure = false;
             }
         }
     }
@@ -191,6 +214,9 @@ TEST_CASE("LEDC memory leak test", "[ledc]")
     }
     TEST_ASSERT_INT32_WITHIN(100, size, esp_get_free_heap_size());
     TEST_ESP_OK(ledc_stop(ledc_time_config.speed_mode, LEDC_CHANNEL_0, 0));
+
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
 }
 
 // duty should be manually checked from the waveform using a logic analyzer
@@ -222,8 +248,7 @@ TEST_CASE("LEDC fade with time", "[ledc]")
     vTaskDelay(210 / portTICK_PERIOD_MS);
     TEST_ASSERT_EQUAL_INT32(0, ledc_get_duty(test_speed_mode, LEDC_CHANNEL_0));
 
-    //deinitialize fade service
+    fade_teardown();
-    ledc_fade_func_uninstall();
 }
 
 TEST_CASE("LEDC fade with step", "[ledc]")
@@ -245,8 +270,7 @@ TEST_CASE("LEDC fade with step", "[ledc]")
     //scaler=0 check
     TEST_ASSERT(ledc_set_fade_with_step(test_speed_mode, LEDC_CHANNEL_0, 4000, 0, 1) == ESP_ERR_INVALID_ARG);
 
-    //deinitialize fade service
+    fade_teardown();
-    ledc_fade_func_uninstall();
 }
 
 TEST_CASE("LEDC fast switching duty with fade_wait_done", "[ledc]")
@@ -276,8 +300,7 @@ TEST_CASE("LEDC fast switching duty with fade_wait_done", "[ledc]")
     vTaskDelay(5 / portTICK_PERIOD_MS);
     TEST_ASSERT_EQUAL_INT32(500, ledc_get_duty(test_speed_mode, LEDC_CHANNEL_0));
 
-    //deinitialize fade service
+    fade_teardown();
-    ledc_fade_func_uninstall();
 }
 
 TEST_CASE("LEDC fast switching duty with fade_no_wait", "[ledc]")
@@ -310,8 +333,7 @@ TEST_CASE("LEDC fast switching duty with fade_no_wait", "[ledc]")
     vTaskDelay(5 / portTICK_PERIOD_MS);
     TEST_ASSERT_EQUAL_INT32(500, ledc_get_duty(test_speed_mode, LEDC_CHANNEL_0));
 
-    //deinitialize fade service
+    fade_teardown();
-    ledc_fade_func_uninstall();
 }
 
 #if SOC_LEDC_SUPPORT_FADE_STOP
@@ -343,8 +365,7 @@ TEST_CASE("LEDC fade stop test", "[ledc]")
     TEST_ASSERT_EQUAL_INT32(duty_after_stop, ledc_get_duty(test_speed_mode, LEDC_CHANNEL_0));
     TEST_ASSERT_NOT_EQUAL(4000, duty_after_stop);
 
-    //deinitialize fade service
+    fade_teardown();
-    ledc_fade_func_uninstall();
 }
 #endif // SOC_LEDC_SUPPORT_FADE_STOP
 
@@ -376,8 +397,7 @@ TEST_CASE("LEDC gamma ram write and read test", "[ledc]")
         TEST_ASSERT_EQUAL_INT32(i + 3, scale);
     }
 
-    // Deinitialize fade service
+    fade_teardown();
-    ledc_fade_func_uninstall();
 }
 
 TEST_CASE("LEDC multi fade test", "[ledc]")
@@ -417,8 +437,7 @@ TEST_CASE("LEDC multi fade test", "[ledc]")
     // Check the duty at the end of the fade
     TEST_ASSERT_EQUAL_INT32((uint32_t)end_duty, ledc_get_duty(test_speed_mode, LEDC_CHANNEL_0));
 
-    // Deinitialize fade service
+    fade_teardown();
-    ledc_fade_func_uninstall();
 }
 #endif // SOC_LEDC_GAMMA_CURVE_FADE_SUPPORTED
 
@@ -482,6 +501,9 @@ TEST_CASE("LEDC set and get frequency", "[ledc][timeout=60]")
     timer_frequency_test(LEDC_CHANNEL_0, LEDC_TIMER_13_BIT, LEDC_TIMER_1, LEDC_HIGH_SPEED_MODE);
     timer_frequency_test(LEDC_CHANNEL_0, LEDC_TIMER_13_BIT, LEDC_TIMER_2, LEDC_HIGH_SPEED_MODE);
     timer_frequency_test(LEDC_CHANNEL_0, LEDC_TIMER_13_BIT, LEDC_TIMER_3, LEDC_HIGH_SPEED_MODE);
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
+    ledc_ch_config.deconfigure = false;
 #endif // SOC_LEDC_SUPPORT_HS_MODE
     ledc_ch_config.speed_mode = LEDC_LOW_SPEED_MODE;
     TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
@@ -489,6 +511,8 @@ TEST_CASE("LEDC set and get frequency", "[ledc][timeout=60]")
     timer_frequency_test(LEDC_CHANNEL_0, LEDC_TIMER_12_BIT, LEDC_TIMER_1, LEDC_LOW_SPEED_MODE);
     timer_frequency_test(LEDC_CHANNEL_0, LEDC_TIMER_12_BIT, LEDC_TIMER_2, LEDC_LOW_SPEED_MODE);
     timer_frequency_test(LEDC_CHANNEL_0, LEDC_TIMER_12_BIT, LEDC_TIMER_3, LEDC_LOW_SPEED_MODE);
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
 }
 
 #if SOC_CLK_TREE_SUPPORTED
@@ -556,6 +580,9 @@ TEST_CASE("LEDC timer select specific clock source", "[ledc]")
     TEST_ESP_OK(ledc_bind_channel_timer(test_speed_mode, LEDC_CHANNEL_0, LEDC_TIMER_0));
     vTaskDelay(1000 / portTICK_PERIOD_MS);
     TEST_ASSERT_EQUAL_INT32(ledc_get_freq(test_speed_mode, LEDC_TIMER_0), 500);
+
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
 }
 #endif  //SOC_CLK_TREE_SUPPORTED
 
@@ -608,6 +635,9 @@ TEST_CASE("LEDC timer pause and resume", "[ledc]")
     vTaskDelay(100 / portTICK_PERIOD_MS);
     count = wave_count(200);
     TEST_ASSERT_UINT32_WITHIN(5, TEST_PWM_FREQ * 200 / 1000, count);
+
+    ledc_ch_config.deconfigure = true;
+    TEST_ESP_OK(ledc_channel_config(&ledc_ch_config));
 }
 
 static void ledc_cpu_reset_test_first_stage(void)