Merge branch 'bugfix/ledc_max_duty_cycle_v5.1' into 'release/v5.1'

fix(ledc): fix ledc driver 100% duty cycle configuration (backport v5.1)

See merge request espressif/esp-idf!27179

components/driver/ledc/ledc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -600,8 +600,13 @@ esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf)
     }
 
     /*set channel parameters*/
-    /*   channel parameters decide how the waveform looks like in one period*/
-    /*   set channel duty and hpoint value, duty range is (0 ~ ((2 ** duty_resolution) - 1)), max hpoint value is 0xfffff*/
+    /*   channel parameters decide how the waveform looks like in one period */
+    /*   set channel duty and hpoint value, duty range is [0, (2**duty_res)], hpoint range is [0, (2**duty_res)-1] */
+    /*   Note: On ESP32, ESP32S2, ESP32S3, ESP32C3, ESP32C2, ESP32C6, ESP32H2, due to a hardware bug,
+     *         100% duty cycle (i.e. 2**duty_res) is not reachable when the binded timer selects the maximum duty
+     *         resolution. For example, the max duty resolution on ESP32C3 is 14-bit width, then set duty to (2**14)
+     *         will mess up the duty calculation in hardware.
+    */
     ledc_set_duty_with_hpoint(speed_mode, ledc_channel, duty, hpoint);
     /*update duty settings*/
     ledc_update_duty(speed_mode, ledc_channel);
@@ -787,7 +792,7 @@ static inline void IRAM_ATTR ledc_calc_fade_end_channel(uint32_t *fade_end_statu
     *channel = i;
 }
 
-void IRAM_ATTR ledc_fade_isr(void *arg)
+static void IRAM_ATTR ledc_fade_isr(void *arg)
 {
     bool cb_yield = false;
     portBASE_TYPE HPTaskAwoken = pdFALSE;
@@ -998,8 +1003,9 @@ static esp_err_t _ledc_set_fade_with_step(ledc_mode_t speed_mode, ledc_channel_t
         ESP_LOGD(LEDC_TAG, "cur duty: %"PRIu32"; target: %"PRIu32", step: %d, cycle: %d; scale: %d; dir: %d\n",
                  duty_cur, target_duty, step_num, cycle_num, scale, dir);
     } else {
+        // Directly set duty to the target, does not care on the dir
         portENTER_CRITICAL(&ledc_spinlock);
-        ledc_duty_config(speed_mode, channel, LEDC_VAL_NO_CHANGE, target_duty, dir, 1, 1, 0);
+        ledc_duty_config(speed_mode, channel, LEDC_VAL_NO_CHANGE, target_duty, 1, 1, 1, 0);
         portEXIT_CRITICAL(&ledc_spinlock);
         ESP_LOGD(LEDC_TAG, "Set to target duty: %"PRIu32, target_duty);
     }
@@ -1159,6 +1165,7 @@ esp_err_t ledc_fade_stop(ledc_mode_t speed_mode, ledc_channel_t channel)
 
 esp_err_t ledc_fade_func_install(int intr_alloc_flags)
 {
+    LEDC_CHECK(s_ledc_fade_isr_handle == NULL, "fade function already installed", ESP_ERR_INVALID_STATE);
     //OR intr_alloc_flags with ESP_INTR_FLAG_IRAM because the fade isr is in IRAM
     return ledc_isr_register(ledc_fade_isr, NULL, intr_alloc_flags | ESP_INTR_FLAG_IRAM, &s_ledc_fade_isr_handle);
 }

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

@@ -239,7 +239,13 @@ To set the duty cycle, use the dedicated function :cpp:func:`ledc_set_duty`. Aft
 
 Another way to set the duty cycle, as well as some other channel parameters, is by calling :cpp:func:`ledc_channel_config` covered in Section :ref:`ledc-api-configure-channel`.
 
-The range of the duty cycle values passed to functions depends on selected ``duty_resolution`` and should be from ``0`` to ``(2 ** duty_resolution) - 1``. For example, if the selected duty resolution is 10, then the duty cycle values can range from 0 to 1023. This provides the resolution of ~0.1%.
+The range of the duty cycle values passed to functions depends on selected ``duty_resolution`` and should be from ``0`` to ``(2 ** duty_resolution)``. For example, if the selected duty resolution is 10, then the duty cycle values can range from 0 to 1024. This provides the resolution of ~ 0.1%.
+
+.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c2 or esp32c6 or esp32h2
+
+    .. warning::
+
+        On {IDF_TARGET_NAME}, when channel's binded timer selects its maximum duty resolution, the duty cycle value cannot be set to ``(2 ** duty_resolution)``. Otherwise, the internal duty counter in the hardware will overflow and be messed up.
 
 
 Change PWM Duty Cycle using Hardware

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

@@ -239,7 +239,13 @@ LED PWM 控制器可在无需 CPU 干预的情况下自动改变占空比，实
 
 另外一种设置占空比和其他通道参数的方式是调用 :ref:`ledc-api-configure-channel` 一节提到的函数 :cpp:func:`ledc_channel_config`。
 
-传递给函数的占空比数值范围取决于选定的 ``duty_resolution``，应为 ``0`` 至 ``(2 ** duty_resolution) - 1``。例如，如选定的占空比分辨率为 10，则占空比的数值范围为 0 至 1023。此时分辨率为 ~0.1%。
+传递给函数的占空比数值范围取决于选定的 ``duty_resolution``，应为 ``0`` 至 ``(2 ** duty_resolution)``。例如，如选定的占空比分辨率为 10，则占空比的数值范围为 0 至 1024。此时分辨率为 ~ 0.1%。
+
+.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c2 or esp32c6 or esp32h2
+
+    .. warning::
+
+        在 {IDF_TARGET_NAME} 上，当通道绑定的定时器配置了其最大 PWM 占空比分辨率（ ``MAX_DUTY_RES`` ），通道的占空比不能被设置到 ``(2 ** MAX_DUTY_RES)`` 。否则，硬件内部占空比计数器会溢出，并导致占空比计算错误。
 
 
 使用硬件改变 PWM 占空比

examples/peripherals/ledc/ledc_basic/README.md

@@ -27,26 +27,26 @@ The example uses fixed PWM frequency of 5 kHz, duty cycle in 50%, and output GPI
 
 Depending on the selected `LEDC_FREQUENCY`, you will need to change the `LEDC_DUTY_RES`.
 
-To dinamicaly set the duty and frequency, you can use the following functions:
+To dynamically set the duty and frequency, you can use the following functions:
 
 To set the frequency to 2.5 kHZ i.e:
 
 ```c
 ledc_set_freq(LEDC_MODE, LEDC_TIMER, 2500);
 ```
 
-Now the duty to 100% i.e:
+Now set the duty to 100% i.e:
 
 ```c
-ledc_set_duty(LEDC_MODE, LEDC_CHANNEL, 8191);
+ledc_set_duty(LEDC_MODE, LEDC_CHANNEL, 8192);
 ledc_update_duty(LEDC_MODE, LEDC_CHANNEL);
 ```
 
 To change the duty cycle you need to calculate the duty range according to the duty resolution.
 
 If duty resolution is 13 bits:
 
-Duty range: `0 to (2 ** 13) - 1 = 8191` where 0 is 0% and 8191 is 100%.
+Duty range: `0 to (2 ** 13) = 8192` where 0 is 0% and 8192 is 100%.
 
 ### Build and Flash
 

examples/peripherals/ledc/ledc_basic/main/ledc_basic_example_main.c

@@ -15,9 +15,15 @@
 #define LEDC_OUTPUT_IO          (5) // Define the output GPIO
 #define LEDC_CHANNEL            LEDC_CHANNEL_0
 #define LEDC_DUTY_RES           LEDC_TIMER_13_BIT // Set duty resolution to 13 bits
-#define LEDC_DUTY               (4095) // Set duty to 50%. ((2 ** 13) - 1) * 50% = 4095
+#define LEDC_DUTY               (4096) // Set duty to 50%. (2 ** 13) * 50% = 4096
 #define LEDC_FREQUENCY          (5000) // Frequency in Hertz. Set frequency at 5 kHz
 
+/* Warning:
+ * For ESP32, ESP32S2, ESP32S3, ESP32C3, ESP32C2, ESP32C6, ESP32H2 targets,
+ * when LEDC_DUTY_RES selects the maximum duty resolution (i.e. value equal to SOC_LEDC_TIMER_BIT_WIDTH),
+ * 100% duty cycle is not reachable (duty cannot be set to (2 ** SOC_LEDC_TIMER_BIT_WIDTH)).
+ */
+
 static void example_ledc_init(void)
 {
     // Prepare and then apply the LEDC PWM timer configuration