Merge branch 'doc/explain_ledc_callback_return_value_v4.4' into 'release/v4.4'

ledc: explain the callback return value (v4.4)

See merge request espressif/esp-idf!20967

components/driver/include/driver/ledc.h

@@ -78,8 +78,9 @@ typedef struct {
  * @brief Type of LEDC event callback
  * @param param LEDC callback parameter
  * @param user_arg User registered data
+ * @return Whether a high priority task has been waken up by this function
  */
-typedef bool (* ledc_cb_t)(const ledc_cb_param_t *param, void *user_arg);
+typedef bool (*ledc_cb_t)(const ledc_cb_param_t *param, void *user_arg);
 
 /**
  * @brief Group of supported LEDC callbacks
@@ -99,7 +100,7 @@ typedef struct {
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG Parameter error
  */
-esp_err_t ledc_channel_config(const ledc_channel_config_t* ledc_conf);
+esp_err_t ledc_channel_config(const ledc_channel_config_t *ledc_conf);
 
 /**
  * @brief LEDC timer configuration
@@ -112,7 +113,7 @@ esp_err_t ledc_channel_config(const ledc_channel_config_t* ledc_conf);
  *     - ESP_ERR_INVALID_ARG Parameter error
  *     - ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution.
  */
-esp_err_t ledc_timer_config(const ledc_timer_config_t* timer_conf);
+esp_err_t ledc_timer_config(const ledc_timer_config_t *timer_conf);
 
 /**
  * @brief LEDC update channel parameters
@@ -285,7 +286,7 @@ esp_err_t ledc_set_fade(ledc_mode_t speed_mode, ledc_channel_t channel, uint32_t
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG Function pointer error.
  */
-esp_err_t ledc_isr_register(void (*fn)(void*), void * arg, int intr_alloc_flags, ledc_isr_handle_t *handle);
+esp_err_t ledc_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, ledc_isr_handle_t *handle);
 
 /**
  * @brief Configure LEDC settings
@@ -496,6 +497,7 @@ esp_err_t ledc_set_fade_step_and_start(ledc_mode_t speed_mode, ledc_channel_t ch
  *     - ESP_FAIL Fade function init error
  */
 esp_err_t ledc_cb_register(ledc_mode_t speed_mode, ledc_channel_t channel, ledc_cbs_t *cbs, void *user_arg);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -108,7 +108,9 @@ The LEDC hardware provides the means to gradually transition from one duty cycle
 * :cpp:func:`ledc_set_fade_with_step`
 * :cpp:func:`ledc_set_fade`
 
-Finally start fading with :cpp:func:`ledc_fade_start`.
+Start fading with :cpp:func:`ledc_fade_start`. A fade can be operated in blocking or non-blocking mode, please check :cpp:enum:`ledc_fade_mode_t` for the difference between the two available fade modes. Note that with either fade mode, the next fade or fixed-duty update will not take effect until the last fade finishes.
+
+To get a notification about the completion of a fade operation, a fade end callback function can be registered for each channel by calling :cpp:func:`ledc_cb_register` after the fade service being installed. The fade end callback prototype is defined in :cpp:type:`ledc_cb_t`, where you should return a boolean value from the callback function, indicating whether a high priority task is woken up by this callback function.
 
 If not required anymore, fading and an associated interrupt can be disabled with :cpp:func:`ledc_fade_func_uninstall`.
 

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

@@ -108,7 +108,9 @@ LED PWM 控制器硬件可逐渐改变占空比的数值。要使用此功能，
 * :cpp:func:`ledc_set_fade_with_step`
 * :cpp:func:`ledc_set_fade`
 
-最后用 :cpp:func:`ledc_fade_start` 开启渐变。
+最后需要调用 :cpp:func:`ledc_fade_start` 开启渐变。渐变可以在阻塞或非阻塞模式下运行，具体区别请查看 :cpp:enum:`ledc_fade_mode_t`。需要特别注意的是，不管在哪种模式下，下一次渐变或单次占空比配置的指令生效都必须等到前一次渐变结束。
+
+此外，在使能渐变后，每个通道都可以额外通过调用 :cpp:func:`ledc_cb_register` 注册一个回调函数用以获得渐变完成的事件通知。回调函数的原型被定义在 :cpp:type:`ledc_cb_t`。每个回调函数都应当返回一个布尔值给驱动的中断处理函数，用以表示是否有高优先级任务被其唤醒。
 
 如不需要渐变和渐变中断，可用函数 :cpp:func:`ledc_fade_func_uninstall` 关闭。