From 9ced54699e14694c0543b4e7e7c7d47206bca9fe Mon Sep 17 00:00:00 2001 From: IhorNehrutsa Date: Fri, 7 Jul 2023 17:42:57 +0300 Subject: [PATCH] feat(ledc): add ledc_find_suitable_duty_resolution helper function Helper function to find the maximum possible duty resolution in bits for ledc_timer_config() Merges https://github.com/espressif/esp-idf/pull/11810 --- components/driver/ledc/include/driver/ledc.h | 14 +++++++- components/driver/ledc/ledc.c | 35 +++++++++++++++++-- docs/en/api-reference/peripherals/ledc.rst | 2 ++ docs/zh_CN/api-reference/peripherals/ledc.rst | 2 ++ 4 files changed, 49 insertions(+), 4 deletions(-) diff --git a/components/driver/ledc/include/driver/ledc.h b/components/driver/ledc/include/driver/ledc.h index bce4e0de4e..a63fc4b16a 100644 --- a/components/driver/ledc/include/driver/ledc.h +++ b/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 diff --git a/components/driver/ledc/ledc.c b/components/driver/ledc/ledc.c index 753c2dd3a1..1e436a3e7d 100644 --- a/components/driver/ledc/ledc.c +++ b/components/driver/ledc/ledc.c @@ -4,6 +4,7 @@ * SPDX-License-Identifier: Apache-2.0 */ #include +#include #include "esp_types.h" #include "freertos/FreeRTOS.h" #include "freertos/semphr.h" @@ -332,9 +333,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); } @@ -849,7 +850,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) diff --git a/docs/en/api-reference/peripherals/ledc.rst b/docs/en/api-reference/peripherals/ledc.rst index 7a29b7fd9a..0095c4f502 100644 --- a/docs/en/api-reference/peripherals/ledc.rst +++ b/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`) diff --git a/docs/zh_CN/api-reference/peripherals/ledc.rst b/docs/zh_CN/api-reference/peripherals/ledc.rst index 55ff9bdce0..ef91526deb 100644 --- a/docs/zh_CN/api-reference/peripherals/ledc.rst +++ b/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`）