Merge branch 'feature/ledc_cal_duty_resolution' into 'master'

feat(ledc): add ledc_find_suitable_duty_resolution function

Closes IDFGH-10569

See merge request espressif/esp-idf!25208

components/driver/ledc/include/driver/ledc.h

@@ -109,7 +109,7 @@ typedef struct {
 
 /**
  * @brief LEDC channel configuration
- *        Configure LEDC channel with the given channel/output gpio_num/interrupt/source timer/frequency(Hz)/LEDC duty resolution
+ *        Configure LEDC channel with the given channel/output gpio_num/interrupt/source timer/frequency(Hz)/LEDC duty
  *
  * @param ledc_conf Pointer of LEDC channel configure struct
  *
@@ -119,6 +119,18 @@ typedef struct {
  */
 esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf);
 
+/**
+ * @brief Helper function to find the maximum possible duty resolution in bits for ledc_timer_config()
+ *
+ * @param src_clk_freq LEDC timer source clock frequency (Hz) (See doxygen comments of `ledc_clk_cfg_t` or get from `esp_clk_tree_src_get_freq_hz`)
+ * @param timer_freq Desired LEDC timer frequency (Hz)
+ *
+ * @return
+ *     - 0 The timer frequency cannot be achieved
+ *     - Others The largest duty resolution value to be set
+ */
+uint32_t ledc_find_suitable_duty_resolution(uint32_t src_clk_freq, uint32_t timer_freq);
+
 /**
  * @brief LEDC timer configuration
  *        Configure LEDC timer with the given source timer/frequency(Hz)/duty_resolution

components/driver/ledc/ledc.c

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 #include <string.h>
+#include <sys/param.h>
 #include "esp_types.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/semphr.h"
@@ -330,9 +331,9 @@ static inline uint32_t ledc_calculate_divisor(uint32_t src_clk_freq, int freq_hz
      * high.
      *
      * NOTE: We are also going to round up the value when necessary, thanks to:
-     * (freq_hz * precision) / 2
+     * (freq_hz * precision / 2)
      */
-    return ( ( (uint64_t) src_clk_freq << LEDC_LL_FRACTIONAL_BITS ) + ((freq_hz * precision) / 2 ) )
+    return ( ( (uint64_t) src_clk_freq << LEDC_LL_FRACTIONAL_BITS ) + freq_hz * precision / 2 )
            / (freq_hz * precision);
 }
 
@@ -852,7 +853,35 @@ uint32_t ledc_get_freq(ledc_mode_t speed_mode, ledc_timer_t timer_num)
         ESP_LOGW(LEDC_TAG, "LEDC timer not configured, call ledc_timer_config to set timer frequency");
         return 0;
     }
-    return (((uint64_t) src_clk_freq << LEDC_LL_FRACTIONAL_BITS) + (uint64_t) precision * clock_divider / 2) / precision / clock_divider;
+    return (((uint64_t) src_clk_freq << LEDC_LL_FRACTIONAL_BITS) + precision * clock_divider / 2) / (precision * clock_divider);
+}
+
+static inline uint32_t ilog2(uint32_t i)
+{
+    assert(i > 0);
+    uint32_t log = 0;
+    while (i >>= 1) {
+        ++log;
+    }
+    return log;
+}
+
+// https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#ledpwm
+uint32_t ledc_find_suitable_duty_resolution(uint32_t src_clk_freq, uint32_t timer_freq)
+{
+    // Highest resolution is calculated when LEDC_CLK_DIV = 1 (i.e. div_param = 1 << LEDC_LL_FRACTIONAL_BITS)
+    uint32_t div = (src_clk_freq + timer_freq / 2) / timer_freq; // rounded
+    uint32_t duty_resolution = MIN(ilog2(div), SOC_LEDC_TIMER_BIT_WIDTH);
+    uint32_t div_param = ledc_calculate_divisor(src_clk_freq, timer_freq, 1 << duty_resolution);
+    if (LEDC_IS_DIV_INVALID(div_param)) {
+        div = src_clk_freq / timer_freq; // truncated
+        duty_resolution = MIN(ilog2(div), SOC_LEDC_TIMER_BIT_WIDTH);
+        div_param = ledc_calculate_divisor(src_clk_freq, timer_freq, 1 << duty_resolution);
+        if (LEDC_IS_DIV_INVALID(div_param)) {
+            duty_resolution = 0;
+        }
+    }
+    return duty_resolution;
 }
 
 static inline void IRAM_ATTR ledc_calc_fade_end_channel(uint32_t *fade_end_status, uint32_t *channel)

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

@@ -202,6 +202,8 @@ The source clock can also limit the PWM frequency. The higher the source clock f
 
         2. For {IDF_TARGET_NAME}, all timers share one clock source. In other words, it is impossible to use different clock sources for different timers.
 
+The LEDC driver offers a helper function :cpp:func:`ledc_find_suitable_duty_resolution` to find the maximum possible resolution for the timer, given the source clock frequency and the desired PWM signal frequency.
+
 When a timer is no longer needed by any channel, it can be deconfigured by calling the same function :cpp:func:`ledc_timer_config`. The configuration structure :cpp:type:`ledc_timer_config_t` passes in should be:
 
 -  :cpp:member:`ledc_timer_config_t::speed_mode` The speed mode of the timer which wants to be deconfigured belongs to (:cpp:type:`ledc_mode_t`)

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

@@ -202,6 +202,8 @@ LED PWM 控制器可在无需 CPU 干预的情况下自动改变占空比，实
 
         2. {IDF_TARGET_NAME} 的所有定时器共用一个时钟源。因此 {IDF_TARGET_NAME} 不支持给不同的定时器配置不同的时钟源。
 
+LEDC 驱动提供了一个辅助函数 :cpp:func:`ledc_find_suitable_duty_resolution`。传入时钟源频率及期望的 PWM 信号频率，这个函数可以直接找到最大可配的占空比分辨率值。
+
 当一个定时器不再被任何通道所需要时，可以通过调用相同的函数 :cpp:func:`ledc_timer_config` 来重置这个定时器。此时，函数入参的配置结构体需要指定：
 
 -  :cpp:member:`ledc_timer_config_t::speed_mode` 重置定时器的所属速度模式 （:cpp:type:`ledc_mode_t`）