From dd4a7d6c5e5f73d73b0bdbcae2eed476d01cd564 Mon Sep 17 00:00:00 2001
From: Adriano Konzen <adriano.konzen@gmail.com>
Date: Wed, 28 Aug 2024 11:09:56 -0300
Subject: [PATCH] feat(LEDC): Adds the ability to set the clock source for the
 LEDC (#10171)

* Adds the ability to set the clock source for the LEDC

* feat(LEDC): Adjusting function names to more suitable

* feat(LEDC):  Fix clock_source to static

* docs(ledc): Document ledc set and get clock source

* docs(ledc): Update ledcSetClockSource description

* ci(pre-commit): Apply automatic fixes

---------

Co-authored-by: Jan Prochazka <90197375+P-R-O-C-H-Y@users.noreply.github.com>
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
---
 cores/esp32/esp32-hal-ledc.c | 21 ++++++++++++++++++---
 cores/esp32/esp32-hal-ledc.h | 17 +++++++++++++++++
 docs/en/api/ledc.rst         | 28 ++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/cores/esp32/esp32-hal-ledc.c b/cores/esp32/esp32-hal-ledc.c
index 15466390eb8..7d748f98a56 100644
--- a/cores/esp32/esp32-hal-ledc.c
+++ b/cores/esp32/esp32-hal-ledc.c
@@ -47,6 +47,21 @@ ledc_periph_t ledc_handle = {0};
 
 static bool fade_initialized = false;
 
+static ledc_clk_cfg_t clock_source = LEDC_DEFAULT_CLK;
+
+ledc_clk_cfg_t ledcGetClockSource(void) {
+  return clock_source;
+}
+
+bool ledcSetClockSource(ledc_clk_cfg_t source) {
+  if (ledc_handle.used_channels) {
+    log_e("Cannot change LEDC clock source! LEDC channels in use.");
+    return false;
+  }
+  clock_source = source;
+  return true;
+}
+
 static bool ledcDetachBus(void *bus) {
   ledc_channel_handle_t *handle = (ledc_channel_handle_t *)bus;
   bool channel_found = false;
@@ -111,7 +126,7 @@ bool ledcAttachChannel(uint8_t pin, uint32_t freq, uint8_t resolution, uint8_t c
       return false;
     }
   } else {
-    ledc_timer_config_t ledc_timer = {.speed_mode = group, .timer_num = timer, .duty_resolution = resolution, .freq_hz = freq, .clk_cfg = LEDC_DEFAULT_CLK};
+    ledc_timer_config_t ledc_timer = {.speed_mode = group, .timer_num = timer, .duty_resolution = resolution, .freq_hz = freq, .clk_cfg = clock_source};
     if (ledc_timer_config(&ledc_timer) != ESP_OK) {
       log_e("ledc setup failed!");
       return false;
@@ -241,7 +256,7 @@ uint32_t ledcWriteTone(uint8_t pin, uint32_t freq) {
 
     uint8_t group = (bus->channel / 8), timer = ((bus->channel / 2) % 4);
 
-    ledc_timer_config_t ledc_timer = {.speed_mode = group, .timer_num = timer, .duty_resolution = 10, .freq_hz = freq, .clk_cfg = LEDC_DEFAULT_CLK};
+    ledc_timer_config_t ledc_timer = {.speed_mode = group, .timer_num = timer, .duty_resolution = 10, .freq_hz = freq, .clk_cfg = clock_source};
 
     if (ledc_timer_config(&ledc_timer) != ESP_OK) {
       log_e("ledcWriteTone configuration failed!");
@@ -292,7 +307,7 @@ uint32_t ledcChangeFrequency(uint8_t pin, uint32_t freq, uint8_t resolution) {
     }
     uint8_t group = (bus->channel / 8), timer = ((bus->channel / 2) % 4);
 
-    ledc_timer_config_t ledc_timer = {.speed_mode = group, .timer_num = timer, .duty_resolution = resolution, .freq_hz = freq, .clk_cfg = LEDC_DEFAULT_CLK};
+    ledc_timer_config_t ledc_timer = {.speed_mode = group, .timer_num = timer, .duty_resolution = resolution, .freq_hz = freq, .clk_cfg = clock_source};
 
     if (ledc_timer_config(&ledc_timer) != ESP_OK) {
       log_e("ledcChangeFrequency failed!");
diff --git a/cores/esp32/esp32-hal-ledc.h b/cores/esp32/esp32-hal-ledc.h
index efa7bf1fe69..5b44aaad452 100644
--- a/cores/esp32/esp32-hal-ledc.h
+++ b/cores/esp32/esp32-hal-ledc.h
@@ -26,6 +26,7 @@ extern "C" {
 #include <stdbool.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/semphr.h"
+#include "hal/ledc_types.h"
 
 typedef enum {
   NOTE_C,
@@ -57,6 +58,22 @@ typedef struct {
 #endif
 } ledc_channel_handle_t;
 
+/**
+ * @brief Get the LEDC clock source.
+ *
+ * @return LEDC clock source.
+ */
+ledc_clk_cfg_t ledcGetClockSource(void);
+
+/**
+ * @brief Set the LEDC clock source.
+ *
+ * @param source LEDC clock source to set.
+ *
+ * @return true if LEDC clock source was successfully set, false otherwise.
+ */
+bool ledcSetClockSource(ledc_clk_cfg_t source);
+
 /**
  * @brief Attach a pin to the LEDC driver, with a given frequency and resolution.
  *        Channel is automatically assigned.
diff --git a/docs/en/api/ledc.rst b/docs/en/api/ledc.rst
index b7fd7b25537..6ea3437bbf5 100644
--- a/docs/en/api/ledc.rst
+++ b/docs/en/api/ledc.rst
@@ -23,6 +23,34 @@ ESP32-H2  6
 Arduino-ESP32 LEDC API
 ----------------------
 
+ledcSetCLockSource
+******************
+
+This function is used to set the LEDC peripheral clock source. Must be called before any LEDC channel is used.
+The default clock source is XTAL clock (``LEDC_USE_XTAL_CLK``) if supported by the SoC, otherwise it is AUTO clock (``LEDC_AUTO_CLK``).
+
+.. code-block:: arduino
+
+    bool ledcSetClockSource(ledc_clk_cfg_t source);
+
+* ``source`` select the clock source for LEDC peripheral.
+
+  * ``LEDC_APB_CLK`` - APB clock.
+  * ``LEDC_REF_CLK`` - REF clock.
+
+This function will return ``true`` if setting the clock source is successful, otherwise it will return ``false``.
+
+ledcGetClockSource
+******************
+
+This function is used to get the LEDC peripheral clock source.
+
+.. code-block:: arduino
+
+    ledc_clk_cfg_t ledcGetClockSource(void);
+
+This function will return the clock source for the LEDC peripheral.
+
 ledcAttach
 **********