From a9c813ca3ee7f0b6b6d8d2c2c6f12b758de9c30c Mon Sep 17 00:00:00 2001
From: morris <maoshengrong@espressif.com>
Date: Wed, 16 Aug 2023 18:53:14 +0800
Subject: [PATCH 1/4] feat(hw_support): add atomic code block for peripheral
 bus clock and reset

---
 .../include/esp_private/periph_ctrl.h         | 59 ++++++++++++++++++-
 components/esp_hw_support/periph_ctrl.c       | 36 +++++++++++
 2 files changed, 94 insertions(+), 1 deletion(-)

diff --git a/components/esp_hw_support/include/esp_private/periph_ctrl.h b/components/esp_hw_support/include/esp_private/periph_ctrl.h
index a20364bd51c..c73c789cf71 100644
--- a/components/esp_hw_support/include/esp_private/periph_ctrl.h
+++ b/components/esp_hw_support/include/esp_private/periph_ctrl.h
@@ -1,16 +1,73 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
 
+#include <stdint.h>
 #include "soc/periph_defs.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @defgroup Reset and Clock Control APIs
+ * @{
+ */
+
+/**
+ * @brief Acquire the RCC lock for a peripheral module
+ *
+ * @note User code protected by this macro should be as short as possible, because it's a critical section
+ * @note This macro will increase the reference lock of that peripheral.
+ *       You can get the value before the increment from the `rc_name` local variable
+ */
+#define PERIPH_RCC_ACQUIRE_ATOMIC(periph, rc_name)                \
+    for (uint8_t rc_name, i = 1, __DECLARE_RCC_RC_ATOMIC_ENV;     \
+         i ? (rc_name = periph_rcc_acquire_enter(periph), 1) : 0; \
+         periph_rcc_acquire_exit(periph, rc_name), i--)
+
+/**
+ * @brief Release the RCC lock for a peripheral module
+ *
+ * @note User code protected by this macro should be as short as possible, because it's a critical section
+ * @note This macro will decrease the reference lock of that peripheral.
+ *       You can get the value before the increment from the `rc_name` local variable
+ */
+#define PERIPH_RCC_RELEASE_ATOMIC(periph, rc_name)                \
+    for (uint8_t rc_name, i = 1, __DECLARE_RCC_RC_ATOMIC_ENV;     \
+         i ? (rc_name = periph_rcc_release_enter(periph), 1) : 0; \
+         periph_rcc_release_exit(periph, rc_name), i--)
+
+/**
+ * @brief A simplified version of `PERIPH_RCC_ACQUIRE/RELEASE_ATOMIC`, without a reference count
+ *
+ * @note User code protected by this macro should be as short as possible, because it's a critical section
+ */
+#define PERIPH_RCC_ATOMIC()                   \
+    for (int i = 1, __DECLARE_RCC_ATOMIC_ENV; \
+         i ? (periph_rcc_enter(), 1) : 0;     \
+         periph_rcc_exit(), i--)
+
+/** @cond */
+// The following functions are not intended to be used directly by the developers
+uint8_t periph_rcc_acquire_enter(periph_module_t periph);
+void periph_rcc_acquire_exit(periph_module_t periph, uint8_t ref_count);
+uint8_t periph_rcc_release_enter(periph_module_t periph);
+void periph_rcc_release_exit(periph_module_t periph, uint8_t ref_count);
+void periph_rcc_enter(void);
+void periph_rcc_exit(void);
+/** @endcond */
+
+/**
+ * @}
+ */
+
+/*************************************************************************************************************
+ * @note The following APIs are no longer supported since ESP32P4, please use the RCC lock macros instead.
+ *************************************************************************************************************/
 /**
  * @brief Enable peripheral module by un-gating the clock and de-asserting the reset signal.
  *
diff --git a/components/esp_hw_support/periph_ctrl.c b/components/esp_hw_support/periph_ctrl.c
index 8c248247167..6db2d8fa1f2 100644
--- a/components/esp_hw_support/periph_ctrl.c
+++ b/components/esp_hw_support/periph_ctrl.c
@@ -13,10 +13,46 @@
 #include "esp_private/esp_modem_clock.h"
 #endif
 
+/// @brief For simplicity and backward compatible, we are using the same spin lock for both bus clock on/off and reset
+/// @note  We may want to split them into two spin locks in the future
 static portMUX_TYPE periph_spinlock = portMUX_INITIALIZER_UNLOCKED;
 
 static uint8_t ref_counts[PERIPH_MODULE_MAX] = {0};
 
+void periph_rcc_enter(void)
+{
+    portENTER_CRITICAL_SAFE(&periph_spinlock);
+}
+
+void periph_rcc_exit(void)
+{
+    portEXIT_CRITICAL_SAFE(&periph_spinlock);
+}
+
+uint8_t periph_rcc_acquire_enter(periph_module_t periph)
+{
+    periph_rcc_enter();
+    return ref_counts[periph];
+}
+
+void periph_rcc_acquire_exit(periph_module_t periph, uint8_t ref_count)
+{
+    ref_counts[periph] = ++ref_count;
+    periph_rcc_exit();
+}
+
+uint8_t periph_rcc_release_enter(periph_module_t periph)
+{
+    periph_rcc_enter();
+    return ref_counts[periph] - 1;
+}
+
+void periph_rcc_release_exit(periph_module_t periph, uint8_t ref_count)
+{
+    ref_counts[periph] = ref_count;
+    periph_rcc_exit();
+}
+
 void periph_module_enable(periph_module_t periph)
 {
     assert(periph < PERIPH_MODULE_MAX);

From 71cf16ec01ffc4eef7e2df819afa3378af807038 Mon Sep 17 00:00:00 2001
From: morris <maoshengrong@espressif.com>
Date: Fri, 18 Aug 2023 13:26:46 +0800
Subject: [PATCH 2/4] feat(gptimer): use RCC atomic block to enable/reset
 peripheral

---
 components/driver/deprecated/timer_legacy.c   | 32 +++++++++--
 components/driver/gptimer/gptimer.c           | 41 +++++++++++---
 components/esp_system/fpga_overrides.c        |  8 ---
 components/esp_system/int_wdt.c               | 12 ++++-
 components/esp_system/port/soc/esp32/clk.c    | 11 +---
 components/esp_system/port/soc/esp32c2/clk.c  | 11 +---
 components/esp_system/port/soc/esp32c3/clk.c  | 11 +---
 components/esp_system/port/soc/esp32c6/clk.c  |  9 ----
 components/esp_system/port/soc/esp32h2/clk.c  |  9 ----
 components/esp_system/port/soc/esp32s2/clk.c  | 11 +---
 components/esp_system/port/soc/esp32s3/clk.c  | 11 +---
 .../task_wdt/task_wdt_impl_timergroup.c       | 16 +++++-
 components/esp_timer/src/esp_timer_impl_lac.c | 13 ++++-
 components/hal/esp32/include/hal/timer_ll.h   | 52 +++++++++++++++++-
 components/hal/esp32c2/include/hal/timer_ll.h | 40 +++++++++++++-
 components/hal/esp32c3/include/hal/timer_ll.h | 48 ++++++++++++++++-
 components/hal/esp32c6/include/hal/timer_ll.h | 47 +++++++++++++++-
 components/hal/esp32h2/include/hal/timer_ll.h | 45 ++++++++++++++++
 .../hal/esp32p4/include/hal/clk_gate_ll.h     | 13 -----
 components/hal/esp32p4/include/hal/timer_ll.h | 53 +++++++++++++++++++
 components/hal/esp32s2/include/hal/timer_ll.h | 52 +++++++++++++++++-
 components/hal/esp32s3/include/hal/timer_ll.h | 48 ++++++++++++++++-
 components/hal/timer_hal.c                    |  4 --
 .../soc/esp32c2/include/soc/system_struct.h   |  1 +
 .../soc/esp32c2/ld/esp32c2.peripherals.ld     |  1 +
 .../soc/esp32c3/ld/esp32c3.peripherals.ld     |  1 +
 .../soc/esp32s3/ld/esp32s3.peripherals.ld     |  1 +
 27 files changed, 488 insertions(+), 113 deletions(-)

diff --git a/components/driver/deprecated/timer_legacy.c b/components/driver/deprecated/timer_legacy.c
index 3db66d5771e..43f42336d05 100644
--- a/components/driver/deprecated/timer_legacy.c
+++ b/components/driver/deprecated/timer_legacy.c
@@ -34,6 +34,12 @@ static const char *TIMER_TAG = "timer_group";
 #define TIMER_ENTER_CRITICAL(mux)      portENTER_CRITICAL_SAFE(mux);
 #define TIMER_EXIT_CRITICAL(mux)       portEXIT_CRITICAL_SAFE(mux);
 
+#if CONFIG_IDF_TARGET_ESP32P4
+#define GPTIMER_CLOCK_SRC_ATOMIC() PERIPH_RCC_ATOMIC()
+#else
+#define GPTIMER_CLOCK_SRC_ATOMIC()
+#endif
+
 typedef struct {
     timer_isr_t fn;  /*!< isr function */
     void *args;      /*!< isr function args */
@@ -305,7 +311,12 @@ esp_err_t timer_init(timer_group_t group_num, timer_idx_t timer_num, const timer
     }
     timer_hal_context_t *hal = &p_timer_obj[group_num][timer_num]->hal;
 
-    periph_module_enable(timer_group_periph_signals.groups[group_num].module);
+    PERIPH_RCC_ACQUIRE_ATOMIC(timer_group_periph_signals.groups[group_num].module, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(group_num, true);
+            timer_ll_reset_register(group_num);
+        }
+    }
 
     TIMER_ENTER_CRITICAL(&timer_spinlock[group_num]);
     timer_hal_init(hal, group_num, timer_num);
@@ -315,9 +326,12 @@ esp_err_t timer_init(timer_group_t group_num, timer_idx_t timer_num, const timer
     if (config->clk_src) {
         clk_src = config->clk_src;
     }
-    // although `clk_src` is of `timer_src_clk_t` type, but it's binary compatible with `gptimer_clock_source_t`,
-    // as the underlying enum entries come from the same `soc_module_clk_t`
-    timer_ll_set_clock_source(p_timer_obj[group_num][timer_num]->hal.dev, timer_num, (gptimer_clock_source_t)clk_src);
+    GPTIMER_CLOCK_SRC_ATOMIC() {
+        // although `clk_src` is of `timer_src_clk_t` type, but it's binary compatible with `gptimer_clock_source_t`,
+        // as the underlying enum entries come from the same `soc_module_clk_t`
+        timer_ll_set_clock_source(p_timer_obj[group_num][timer_num]->hal.dev, timer_num, (gptimer_clock_source_t)clk_src);
+        timer_ll_enable_clock(hal->dev, timer_num, true);
+    }
     timer_ll_set_clock_prescale(hal->dev, timer_num, config->divider);
     timer_ll_set_count_direction(p_timer_obj[group_num][timer_num]->hal.dev, timer_num, config->counter_dir);
     timer_ll_enable_intr(hal->dev, TIMER_LL_EVENT_ALARM(timer_num), false);
@@ -343,12 +357,22 @@ esp_err_t timer_deinit(timer_group_t group_num, timer_idx_t timer_num)
     ESP_RETURN_ON_FALSE(p_timer_obj[group_num][timer_num] != NULL, ESP_ERR_INVALID_ARG, TIMER_TAG,  TIMER_NEVER_INIT_ERROR);
     timer_hal_context_t *hal = &p_timer_obj[group_num][timer_num]->hal;
 
+    // disable the source clock
+    GPTIMER_CLOCK_SRC_ATOMIC() {
+        timer_ll_enable_clock(hal->dev, hal->timer_id, false);
+    }
     TIMER_ENTER_CRITICAL(&timer_spinlock[group_num]);
     timer_ll_enable_intr(hal->dev, TIMER_LL_EVENT_ALARM(timer_num), false);
     timer_ll_clear_intr_status(hal->dev, TIMER_LL_EVENT_ALARM(timer_num));
     timer_hal_deinit(hal);
     TIMER_EXIT_CRITICAL(&timer_spinlock[group_num]);
 
+    PERIPH_RCC_RELEASE_ATOMIC(timer_group_periph_signals.groups[group_num].module, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(group_num, false);
+        }
+    }
+
     free(p_timer_obj[group_num][timer_num]);
     p_timer_obj[group_num][timer_num] = NULL;
 
diff --git a/components/driver/gptimer/gptimer.c b/components/driver/gptimer/gptimer.c
index fc7322759bf..cf1b2ec797e 100644
--- a/components/driver/gptimer/gptimer.c
+++ b/components/driver/gptimer/gptimer.c
@@ -32,6 +32,12 @@
 
 static const char *TAG = "gptimer";
 
+#if CONFIG_IDF_TARGET_ESP32P4
+#define GPTIMER_CLOCK_SRC_ATOMIC() PERIPH_RCC_ATOMIC()
+#else
+#define GPTIMER_CLOCK_SRC_ATOMIC()
+#endif
+
 typedef struct gptimer_platform_t {
     _lock_t mutex;                             // platform level mutex lock
     gptimer_group_t *groups[SOC_TIMER_GROUPS]; // timer group pool
@@ -163,8 +169,13 @@ esp_err_t gptimer_del_timer(gptimer_handle_t timer)
     gptimer_clock_source_t clk_src = timer->clk_src;
     int group_id = group->group_id;
     int timer_id = timer->timer_id;
+    timer_hal_context_t *hal = &timer->hal;
     ESP_LOGD(TAG, "del timer (%d,%d)", group_id, timer_id);
-    timer_hal_deinit(&timer->hal);
+    // disable the source clock
+    GPTIMER_CLOCK_SRC_ATOMIC() {
+        timer_ll_enable_clock(hal->dev, hal->timer_id, false);
+    }
+    timer_hal_deinit(hal);
     // recycle memory resource
     ESP_RETURN_ON_ERROR(gptimer_destroy(timer), TAG, "destroy gptimer failed");
 
@@ -382,8 +393,6 @@ static gptimer_group_t *gptimer_acquire_group_handle(int group_id)
             // initialize timer group members
             group->group_id = group_id;
             group->spinlock = (portMUX_TYPE)portMUX_INITIALIZER_UNLOCKED;
-            // enable APB access timer registers
-            periph_module_enable(timer_group_periph_signals.groups[group_id].module);
         }
     } else {
         group = s_platform.groups[group_id];
@@ -395,6 +404,15 @@ static gptimer_group_t *gptimer_acquire_group_handle(int group_id)
     _lock_release(&s_platform.mutex);
 
     if (new_group) {
+        // !!! HARDWARE SHARED RESOURCE !!!
+        // the gptimer and watchdog reside in the same the timer group
+        // we need to increase/decrease the reference count before enable/disable/reset the peripheral
+        PERIPH_RCC_ACQUIRE_ATOMIC(timer_group_periph_signals.groups[group_id].module, ref_count) {
+            if (ref_count == 0) {
+                timer_ll_enable_bus_clock(group_id, true);
+                timer_ll_reset_register(group_id);
+            }
+        }
         ESP_LOGD(TAG, "new group (%d) @%p", group_id, group);
     }
 
@@ -412,11 +430,16 @@ static void gptimer_release_group_handle(gptimer_group_t *group)
         assert(s_platform.groups[group_id]);
         do_deinitialize = true;
         s_platform.groups[group_id] = NULL;
-        periph_module_disable(timer_group_periph_signals.groups[group_id].module);
     }
     _lock_release(&s_platform.mutex);
 
     if (do_deinitialize) {
+        // disable bus clock for the timer group
+        PERIPH_RCC_RELEASE_ATOMIC(timer_group_periph_signals.groups[group_id].module, ref_count) {
+            if (ref_count == 0) {
+                timer_ll_enable_bus_clock(group_id, false);
+            }
+        }
         free(group);
         ESP_LOGD(TAG, "del group (%d)", group_id);
     }
@@ -476,9 +499,15 @@ static esp_err_t gptimer_select_periph_clock(gptimer_t *timer, gptimer_clock_sou
     }
 #endif // CONFIG_PM_ENABLE
 
-    timer_ll_set_clock_source(timer->hal.dev, timer_id, src_clk);
+    // !!! HARDWARE SHARED RESOURCE !!!
+    // on some ESP chip, different peripheral's clock source setting are mixed in the same register
+    // so we need to make this done in an atomic way
+    GPTIMER_CLOCK_SRC_ATOMIC() {
+        timer_ll_set_clock_source(timer->hal.dev, timer_id, src_clk);
+        timer_ll_enable_clock(timer->hal.dev, timer_id, true);
+    }
     timer->clk_src = src_clk;
-    unsigned int prescale = counter_src_hz / resolution_hz; // potential resolution loss here
+    uint32_t prescale = counter_src_hz / resolution_hz; // potential resolution loss here
     timer_ll_set_clock_prescale(timer->hal.dev, timer_id, prescale);
     timer->resolution_hz = counter_src_hz / prescale; // this is the real resolution
     if (timer->resolution_hz != resolution_hz) {
diff --git a/components/esp_system/fpga_overrides.c b/components/esp_system/fpga_overrides.c
index 2439c160008..210517bb573 100644
--- a/components/esp_system/fpga_overrides.c
+++ b/components/esp_system/fpga_overrides.c
@@ -77,14 +77,6 @@ void esp_clk_init(void)
 
 void esp_perip_clk_init(void)
 {
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
 
 /**
diff --git a/components/esp_system/int_wdt.c b/components/esp_system/int_wdt.c
index e079948f09e..427634b404a 100644
--- a/components/esp_system/int_wdt.c
+++ b/components/esp_system/int_wdt.c
@@ -11,6 +11,7 @@
 #include "soc/soc_caps.h"
 #include "hal/wdt_hal.h"
 #include "hal/mwdt_ll.h"
+#include "hal/timer_ll.h"
 #include "freertos/FreeRTOS.h"
 #include "esp_cpu.h"
 #include "esp_err.h"
@@ -30,6 +31,8 @@
 #define IWDT_TICKS_PER_US       500
 #define IWDT_INSTANCE           WDT_MWDT1
 #define IWDT_INITIAL_TIMEOUT_S  5
+#define IWDT_PERIPH             PERIPH_TIMG1_MODULE
+#define IWDT_TIMER_GROUP        1
 
 #else
 
@@ -38,6 +41,8 @@
 #define IWDT_TICKS_PER_US       500
 #define IWDT_INSTANCE           WDT_MWDT0
 #define IWDT_INITIAL_TIMEOUT_S  5
+#define IWDT_PERIPH             PERIPH_TIMG0_MODULE
+#define IWDT_TIMER_GROUP        0
 
 #endif // SOC_TIMER_GROUPS > 1
 
@@ -99,7 +104,12 @@ static void IRAM_ATTR tick_hook(void)
 
 void esp_int_wdt_init(void)
 {
-    periph_module_enable(PERIPH_TIMG1_MODULE);
+    PERIPH_RCC_ACQUIRE_ATOMIC(IWDT_PERIPH, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(IWDT_TIMER_GROUP, true);
+            timer_ll_reset_register(IWDT_TIMER_GROUP);
+        }
+    }
     /*
      * Initialize the WDT timeout stages. Note that the initial timeout is set to 5 seconds as variable startup times of
      * each CPU can lead to a timeout. The tick hooks will set the WDT timers to the actual timeout.
diff --git a/components/esp_system/port/soc/esp32/clk.c b/components/esp_system/port/soc/esp32/clk.c
index 5ec87cca7f1..8772a3158bd 100644
--- a/components/esp_system/port/soc/esp32/clk.c
+++ b/components/esp_system/port/soc/esp32/clk.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -300,15 +300,6 @@ __attribute__((weak)) void esp_perip_clk_init(void)
 
     /* Enable RNG clock. */
     periph_module_enable(PERIPH_RNG_MODULE);
-
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
 
 void rtc_clk_select_rtc_slow_clk(void)
diff --git a/components/esp_system/port/soc/esp32c2/clk.c b/components/esp_system/port/soc/esp32c2/clk.c
index f5c1e2ffa63..ebeda2a9b82 100644
--- a/components/esp_system/port/soc/esp32c2/clk.c
+++ b/components/esp_system/port/soc/esp32c2/clk.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
  */
@@ -251,13 +251,4 @@ __attribute__((weak)) void esp_perip_clk_init(void)
 
     /* Enable RNG clock. */
     periph_module_enable(PERIPH_RNG_MODULE);
-
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
diff --git a/components/esp_system/port/soc/esp32c3/clk.c b/components/esp_system/port/soc/esp32c3/clk.c
index 21d256617a2..5dd4710eb97 100644
--- a/components/esp_system/port/soc/esp32c3/clk.c
+++ b/components/esp_system/port/soc/esp32c3/clk.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -294,13 +294,4 @@ __attribute__((weak)) void esp_perip_clk_init(void)
 
     /* Enable RNG clock. */
     periph_module_enable(PERIPH_RNG_MODULE);
-
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
diff --git a/components/esp_system/port/soc/esp32c6/clk.c b/components/esp_system/port/soc/esp32c6/clk.c
index fa1d6682e1c..2f309bd27ee 100644
--- a/components/esp_system/port/soc/esp32c6/clk.c
+++ b/components/esp_system/port/soc/esp32c6/clk.c
@@ -294,13 +294,4 @@ __attribute__((weak)) void esp_perip_clk_init(void)
     /* Enable RNG clock. */
     periph_module_enable(PERIPH_RNG_MODULE);
 #endif
-
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
diff --git a/components/esp_system/port/soc/esp32h2/clk.c b/components/esp_system/port/soc/esp32h2/clk.c
index 7b3e363685a..4aa76ca57bb 100644
--- a/components/esp_system/port/soc/esp32h2/clk.c
+++ b/components/esp_system/port/soc/esp32h2/clk.c
@@ -286,13 +286,4 @@ __attribute__((weak)) void esp_perip_clk_init(void)
     /* Enable RNG clock. */
     periph_module_enable(PERIPH_RNG_MODULE);
 #endif
-
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
diff --git a/components/esp_system/port/soc/esp32s2/clk.c b/components/esp_system/port/soc/esp32s2/clk.c
index dda6cd264ba..4c1fac66812 100644
--- a/components/esp_system/port/soc/esp32s2/clk.c
+++ b/components/esp_system/port/soc/esp32s2/clk.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -312,13 +312,4 @@ __attribute__((weak)) void esp_perip_clk_init(void)
 
     /* Enable RNG clock. */
     periph_module_enable(PERIPH_RNG_MODULE);
-
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
diff --git a/components/esp_system/port/soc/esp32s3/clk.c b/components/esp_system/port/soc/esp32s3/clk.c
index 8d25f506ecc..07b1b933ed8 100644
--- a/components/esp_system/port/soc/esp32s3/clk.c
+++ b/components/esp_system/port/soc/esp32s3/clk.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -314,13 +314,4 @@ __attribute__((weak)) void esp_perip_clk_init(void)
 
     /* Enable RNG clock. */
     periph_module_enable(PERIPH_RNG_MODULE);
-
-    /* Enable TimerGroup 0 clock to ensure its reference counter will never
-     * be decremented to 0 during normal operation and preventing it from
-     * being disabled.
-     * If the TimerGroup 0 clock is disabled and then reenabled, the watchdog
-     * registers (Flashboot protection included) will be reenabled, and some
-     * seconds later, will trigger an unintended reset.
-     */
-    periph_module_enable(PERIPH_TIMG0_MODULE);
 }
diff --git a/components/esp_system/task_wdt/task_wdt_impl_timergroup.c b/components/esp_system/task_wdt/task_wdt_impl_timergroup.c
index ebf8e4c1d07..8b6b1c0b7f5 100644
--- a/components/esp_system/task_wdt/task_wdt_impl_timergroup.c
+++ b/components/esp_system/task_wdt/task_wdt_impl_timergroup.c
@@ -10,6 +10,7 @@
 #include "sdkconfig.h"
 #include "hal/wdt_hal.h"
 #include "hal/mwdt_ll.h"
+#include "hal/timer_ll.h"
 #include "esp_err.h"
 #include "esp_attr.h"
 #include "esp_intr_alloc.h"
@@ -21,6 +22,7 @@
 #define TWDT_TICKS_PER_US       500
 #define TWDT_PRESCALER          MWDT_LL_DEFAULT_CLK_PRESCALER   // Tick period of 500us if WDT source clock is 80MHz
 #define TWDT_PERIPH_MODULE      PERIPH_TIMG0_MODULE
+#define TWDT_TIMER_GROUP        0
 #define TWDT_INTR_SOURCE        ETS_TG0_WDT_LEVEL_INTR_SOURCE
 
 /**
@@ -55,7 +57,13 @@ esp_err_t esp_task_wdt_impl_timer_allocate(const esp_task_wdt_config_t *config,
     }
 
     if (ret == ESP_OK) {
-        periph_module_enable(TWDT_PERIPH_MODULE);
+        // enable bus clock for the timer group registers
+        PERIPH_RCC_ACQUIRE_ATOMIC(TWDT_PERIPH_MODULE, ref_count) {
+            if (ref_count == 0) {
+                timer_ll_enable_bus_clock(TWDT_TIMER_GROUP, true);
+                timer_ll_reset_register(TWDT_TIMER_GROUP);
+            }
+        }
         wdt_hal_init(&ctx->hal, TWDT_INSTANCE, TWDT_PRESCALER, true);
 
         wdt_hal_write_protect_disable(&ctx->hal);
@@ -106,7 +114,11 @@ void esp_task_wdt_impl_timer_free(twdt_ctx_t obj)
         ESP_ERROR_CHECK(esp_intr_disable(ctx->intr_handle));
 
         /* Disable the Timer Group module */
-        periph_module_disable(TWDT_PERIPH_MODULE);
+        PERIPH_RCC_RELEASE_ATOMIC(TWDT_PERIPH_MODULE, ref_count) {
+            if (ref_count == 0) {
+                timer_ll_enable_bus_clock(TWDT_TIMER_GROUP, false);
+            }
+        }
 
         /* Deregister interrupt */
         ESP_ERROR_CHECK(esp_intr_free(ctx->intr_handle));
diff --git a/components/esp_timer/src/esp_timer_impl_lac.c b/components/esp_timer/src/esp_timer_impl_lac.c
index 397cee81f0c..294c6b5662a 100644
--- a/components/esp_timer/src/esp_timer_impl_lac.c
+++ b/components/esp_timer/src/esp_timer_impl_lac.c
@@ -18,6 +18,7 @@
 #include "soc/soc.h"
 #include "soc/timer_group_reg.h"
 #include "soc/rtc.h"
+#include "hal/timer_ll.h"
 #include "freertos/FreeRTOS.h"
 
 /**
@@ -245,7 +246,12 @@ void esp_timer_impl_advance(int64_t time_diff_us)
 
 esp_err_t esp_timer_impl_early_init(void)
 {
-    periph_module_enable(PERIPH_LACT);
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_LACT, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(LACT_MODULE, true);
+            timer_ll_reset_register(LACT_MODULE);
+        }
+    }
 
     REG_WRITE(CONFIG_REG, 0);
     REG_WRITE(LOAD_LO_REG, 0);
@@ -319,6 +325,11 @@ void esp_timer_impl_deinit(void)
         }
     }
     s_alarm_handler = NULL;
+    PERIPH_RCC_RELEASE_ATOMIC(PERIPH_LACT, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(LACT_MODULE, false);
+        }
+    }
 }
 
 uint64_t esp_timer_impl_get_alarm_reg(void)
diff --git a/components/hal/esp32/include/hal/timer_ll.h b/components/hal/esp32/include/hal/timer_ll.h
index 98cf9038f74..4a521411525 100644
--- a/components/hal/esp32/include/hal/timer_ll.h
+++ b/components/hal/esp32/include/hal/timer_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,6 +13,7 @@
 #include "hal/misc.h"
 #include "hal/timer_types.h"
 #include "soc/timer_group_struct.h"
+#include "soc/dport_reg.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,6 +23,55 @@ extern "C" {
 #define TIMER_LL_GET_HW(group_id) ((group_id == 0) ? (&TIMERG0) : (&TIMERG1))
 #define TIMER_LL_EVENT_ALARM(timer_id) (1 << (timer_id))
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    uint32_t reg_val = DPORT_READ_PERI_REG(DPORT_PERIP_CLK_EN_REG);
+    if (group_id == 0) {
+        reg_val &= ~DPORT_TIMERGROUP_CLK_EN;
+        reg_val |= enable << 13;
+    } else {
+        reg_val &= ~DPORT_TIMERGROUP1_CLK_EN;
+        reg_val |= enable << 15;
+    }
+    DPORT_WRITE_PERI_REG(DPORT_PERIP_CLK_EN_REG, reg_val);
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, DPORT_TIMERGROUP_RST);
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, 0);
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, DPORT_TIMERGROUP1_RST);
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, 0);
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
diff --git a/components/hal/esp32c2/include/hal/timer_ll.h b/components/hal/esp32c2/include/hal/timer_ll.h
index 7336306f713..c6f7645cc40 100644
--- a/components/hal/esp32c2/include/hal/timer_ll.h
+++ b/components/hal/esp32c2/include/hal/timer_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,6 +13,7 @@
 #include "hal/misc.h"
 #include "hal/timer_types.h"
 #include "soc/timer_group_struct.h"
+#include "soc/system_struct.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,6 +23,43 @@ extern "C" {
 #define TIMER_LL_GET_HW(group_id) (&TIMERG0)
 #define TIMER_LL_EVENT_ALARM(timer_id) (1 << (timer_id))
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    (void)group_id;
+    SYSTEM.perip_clk_en0.timergroup_clk_en = enable;
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    (void)group_id;
+    SYSTEM.perip_rst_en0.timergroup_rst = 1;
+    SYSTEM.perip_rst_en0.timergroup_rst = 0;
+    TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
diff --git a/components/hal/esp32c3/include/hal/timer_ll.h b/components/hal/esp32c3/include/hal/timer_ll.h
index 817387cebaf..c8e7cd86e8d 100644
--- a/components/hal/esp32c3/include/hal/timer_ll.h
+++ b/components/hal/esp32c3/include/hal/timer_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,6 +13,7 @@
 #include "hal/misc.h"
 #include "hal/timer_types.h"
 #include "soc/timer_group_struct.h"
+#include "soc/system_struct.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,6 +23,51 @@ extern "C" {
 #define TIMER_LL_GET_HW(group_id) ((group_id == 0) ? (&TIMERG0) : (&TIMERG1))
 #define TIMER_LL_EVENT_ALARM(timer_id) (1 << (timer_id))
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    if (group_id == 0) {
+        SYSTEM.perip_clk_en0.reg_timergroup_clk_en = enable;
+    } else {
+        SYSTEM.perip_clk_en0.reg_timergroup1_clk_en = enable;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        SYSTEM.perip_rst_en0.reg_timergroup_rst = 1;
+        SYSTEM.perip_rst_en0.reg_timergroup_rst = 0;
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        SYSTEM.perip_rst_en0.reg_timergroup1_rst = 1;
+        SYSTEM.perip_rst_en0.reg_timergroup1_rst = 0;
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
diff --git a/components/hal/esp32c6/include/hal/timer_ll.h b/components/hal/esp32c6/include/hal/timer_ll.h
index 592cf60e6c3..d255f6a0b5c 100644
--- a/components/hal/esp32c6/include/hal/timer_ll.h
+++ b/components/hal/esp32c6/include/hal/timer_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -50,6 +50,51 @@ extern "C" {
                         }},                                                                \
     }[group][timer][event]
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    if (group_id == 0) {
+        PCR.timergroup0_conf.tg0_clk_en = enable;
+    } else {
+        PCR.timergroup1_conf.tg1_clk_en = enable;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        PCR.timergroup0_conf.tg0_rst_en = 1;
+        PCR.timergroup0_conf.tg0_rst_en = 0;
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        PCR.timergroup1_conf.tg1_rst_en = 1;
+        PCR.timergroup1_conf.tg1_rst_en = 0;
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
diff --git a/components/hal/esp32h2/include/hal/timer_ll.h b/components/hal/esp32h2/include/hal/timer_ll.h
index 17574d6457d..7c27843c034 100644
--- a/components/hal/esp32h2/include/hal/timer_ll.h
+++ b/components/hal/esp32h2/include/hal/timer_ll.h
@@ -50,6 +50,51 @@ extern "C" {
                         }},                                                                \
     }[group][timer][event]
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    if (group_id == 0) {
+        PCR.timergroup0_conf.tg0_clk_en = enable;
+    } else {
+        PCR.timergroup1_conf.tg1_clk_en = enable;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        PCR.timergroup0_conf.tg0_rst_en = 1;
+        PCR.timergroup0_conf.tg0_rst_en = 0;
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        PCR.timergroup1_conf.tg1_rst_en = 1;
+        PCR.timergroup1_conf.tg1_rst_en = 0;
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
diff --git a/components/hal/esp32p4/include/hal/clk_gate_ll.h b/components/hal/esp32p4/include/hal/clk_gate_ll.h
index b9fdf50dd5c..2de987c3828 100644
--- a/components/hal/esp32p4/include/hal/clk_gate_ll.h
+++ b/components/hal/esp32p4/include/hal/clk_gate_ll.h
@@ -80,10 +80,6 @@ static inline uint32_t periph_ll_get_clk_en_mask(periph_module_t periph)
         return HP_SYS_CLKRST_REG_MCPWM0_APB_CLK_EN;
     case PERIPH_MCPWM1_MODULE:
         return HP_SYS_CLKRST_REG_MCPWM1_APB_CLK_EN;
-    case PERIPH_TIMG0_MODULE:
-        return HP_SYS_CLKRST_REG_TIMERGRP0_T0_CLK_EN | HP_SYS_CLKRST_REG_TIMERGRP0_T1_CLK_EN | HP_SYS_CLKRST_REG_TIMERGRP0_WDT_CLK_EN;
-    case PERIPH_TIMG1_MODULE:
-        return HP_SYS_CLKRST_REG_TIMERGRP1_T0_CLK_EN | HP_SYS_CLKRST_REG_TIMERGRP1_T1_CLK_EN | HP_SYS_CLKRST_REG_TIMERGRP1_WDT_CLK_EN;
     case PERIPH_SYSTIMER_MODULE:
         return HP_SYS_CLKRST_REG_SYSTIMER_CLK_EN;
     case PERIPH_LEDC_MODULE:
@@ -148,10 +144,6 @@ static inline uint32_t periph_ll_get_rst_en_mask(periph_module_t periph, bool en
         return HP_SYS_CLKRST_REG_RST_EN_AXI_PDMA;
     case PERIPH_SYSTIMER_MODULE:
         return HP_SYS_CLKRST_REG_RST_EN_STIMER;
-    case PERIPH_TIMG0_MODULE:
-        return HP_SYS_CLKRST_REG_RST_EN_TIMERGRP0;
-    case PERIPH_TIMG1_MODULE:
-        return HP_SYS_CLKRST_REG_RST_EN_TIMERGRP1;
     case PERIPH_UART0_MODULE:
         return HP_SYS_CLKRST_REG_RST_EN_UART0_CORE;
     case PERIPH_UART1_MODULE:
@@ -268,9 +260,6 @@ static inline uint32_t periph_ll_get_clk_en_reg(periph_module_t periph)
     case PERIPH_MCPWM1_MODULE:
     case PERIPH_PCNT_MODULE:
         return HP_SYS_CLKRST_SOC_CLK_CTRL2_REG;
-    case PERIPH_TIMG0_MODULE:
-        return HP_SYS_CLKRST_PERI_CLK_CTRL20_REG;
-    case PERIPH_TIMG1_MODULE:
     case PERIPH_SYSTIMER_MODULE:
     case PERIPH_LEDC_MODULE:
     case PERIPH_RMT_MODULE:
@@ -312,8 +301,6 @@ static inline uint32_t periph_ll_get_rst_en_reg(periph_module_t periph)
     case PERIPH_AHB_PDMA_MODULE:
     case PERIPH_AXI_PDMA_MODULE:
     case PERIPH_SYSTIMER_MODULE:
-    case PERIPH_TIMG0_MODULE:
-    case PERIPH_TIMG1_MODULE:
     case PERIPH_UART0_MODULE:
     case PERIPH_UART1_MODULE:
     case PERIPH_UART2_MODULE:
diff --git a/components/hal/esp32p4/include/hal/timer_ll.h b/components/hal/esp32p4/include/hal/timer_ll.h
index 2b127b19c80..d886e30ce96 100644
--- a/components/hal/esp32p4/include/hal/timer_ll.h
+++ b/components/hal/esp32p4/include/hal/timer_ll.h
@@ -24,6 +24,51 @@ extern "C" {
 #define TIMER_LL_GET_HW(group_id) ((group_id == 0) ? (&TIMERG0) : (&TIMERG1))
 #define TIMER_LL_EVENT_ALARM(timer_id) (1 << (timer_id))
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    if (group_id == 0) {
+        HP_SYS_CLKRST.soc_clk_ctrl2.reg_timergrp0_apb_clk_en = enable;
+    } else {
+        HP_SYS_CLKRST.soc_clk_ctrl2.reg_timergrp1_apb_clk_en = enable;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        HP_SYS_CLKRST.hp_rst_en1.reg_rst_en_timergrp0 = 1;
+        HP_SYS_CLKRST.hp_rst_en1.reg_rst_en_timergrp0 = 0;
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        HP_SYS_CLKRST.hp_rst_en1.reg_rst_en_timergrp1 = 1;
+        HP_SYS_CLKRST.hp_rst_en1.reg_rst_en_timergrp1 = 0;
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
@@ -63,6 +108,10 @@ static inline void timer_ll_set_clock_source(timg_dev_t *hw, uint32_t timer_num,
     }
 }
 
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_ATOMIC_ENV variable in advance
+#define timer_ll_set_clock_source(...) (void)__DECLARE_RCC_ATOMIC_ENV; timer_ll_set_clock_source(__VA_ARGS__)
+
 /**
  * @brief Enable Timer Group (GPTimer) module clock
  *
@@ -87,6 +136,10 @@ static inline void timer_ll_enable_clock(timg_dev_t *hw, uint32_t timer_num, boo
     }
 }
 
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_clock(...) (void)__DECLARE_RCC_ATOMIC_ENV; timer_ll_enable_clock(__VA_ARGS__)
+
 /**
  * @brief Enable alarm event
  *
diff --git a/components/hal/esp32s2/include/hal/timer_ll.h b/components/hal/esp32s2/include/hal/timer_ll.h
index f50a27cb2b2..aae6114a2ee 100644
--- a/components/hal/esp32s2/include/hal/timer_ll.h
+++ b/components/hal/esp32s2/include/hal/timer_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,6 +13,7 @@
 #include "hal/misc.h"
 #include "hal/timer_types.h"
 #include "soc/timer_group_struct.h"
+#include "soc/system_reg.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,6 +23,55 @@ extern "C" {
 #define TIMER_LL_GET_HW(group_id) ((group_id == 0) ? (&TIMERG0) : (&TIMERG1))
 #define TIMER_LL_EVENT_ALARM(timer_id) (1 << (timer_id))
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    uint32_t reg_val = READ_PERI_REG(DPORT_PERIP_CLK_EN0_REG);
+    if (group_id == 0) {
+        reg_val &= ~DPORT_TIMERGROUP_CLK_EN_M;
+        reg_val |= enable << DPORT_TIMERGROUP_CLK_EN_S;
+    } else {
+        reg_val &= ~DPORT_TIMERGROUP1_CLK_EN_M;
+        reg_val |= enable << DPORT_TIMERGROUP1_CLK_EN_S;
+    }
+    WRITE_PERI_REG(DPORT_PERIP_CLK_EN0_REG, reg_val);
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        WRITE_PERI_REG(DPORT_PERIP_RST_EN0_REG, DPORT_TIMERGROUP_RST_M);
+        WRITE_PERI_REG(DPORT_PERIP_RST_EN0_REG, 0);
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        WRITE_PERI_REG(DPORT_PERIP_RST_EN0_REG, DPORT_TIMERGROUP1_RST_M);
+        WRITE_PERI_REG(DPORT_PERIP_RST_EN0_REG, 0);
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
diff --git a/components/hal/esp32s3/include/hal/timer_ll.h b/components/hal/esp32s3/include/hal/timer_ll.h
index f72a67efe62..0da727256ca 100644
--- a/components/hal/esp32s3/include/hal/timer_ll.h
+++ b/components/hal/esp32s3/include/hal/timer_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,6 +13,7 @@
 #include "hal/misc.h"
 #include "hal/timer_types.h"
 #include "soc/timer_group_struct.h"
+#include "soc/system_struct.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,6 +23,51 @@ extern "C" {
 #define TIMER_LL_GET_HW(group_id) ((group_id == 0) ? (&TIMERG0) : (&TIMERG1))
 #define TIMER_LL_EVENT_ALARM(timer_id) (1 << (timer_id))
 
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void timer_ll_enable_bus_clock(int group_id, bool enable)
+{
+    if (group_id == 0) {
+        SYSTEM.perip_clk_en0.timergroup_clk_en = enable;
+    } else {
+        SYSTEM.perip_clk_en0.timergroup1_clk_en = enable;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_enable_bus_clock(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_enable_bus_clock(__VA_ARGS__)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void timer_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        SYSTEM.perip_rst_en0.timergroup_rst = 1;
+        SYSTEM.perip_rst_en0.timergroup_rst = 0;
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        SYSTEM.perip_rst_en0.timergroup1_rst = 1;
+        SYSTEM.perip_rst_en0.timergroup1_rst = 0;
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
 /**
  * @brief Set clock source for timer
  *
diff --git a/components/hal/timer_hal.c b/components/hal/timer_hal.c
index 39f466bca9d..81e1229f783 100644
--- a/components/hal/timer_hal.c
+++ b/components/hal/timer_hal.c
@@ -13,8 +13,6 @@ void timer_hal_init(timer_hal_context_t *hal, uint32_t group_num, uint32_t timer
 {
     hal->dev = TIMER_LL_GET_HW(group_num);
     hal->timer_id = timer_num;
-    // enable peripheral clock
-    timer_ll_enable_clock(hal->dev, timer_num, true);
     // stop counter, alarm, auto-reload at first place
     timer_ll_enable_counter(hal->dev, timer_num, false);
     timer_ll_enable_auto_reload(hal->dev, timer_num, false);
@@ -27,8 +25,6 @@ void timer_hal_init(timer_hal_context_t *hal, uint32_t group_num, uint32_t timer
 
 void timer_hal_deinit(timer_hal_context_t *hal)
 {
-    // disable peripheral clock
-    timer_ll_enable_clock(hal->dev, hal->timer_id, false);
     // ensure counter, alarm, auto-reload are disabled
     timer_ll_enable_counter(hal->dev, hal->timer_id, false);
     timer_ll_enable_auto_reload(hal->dev, hal->timer_id, false);
diff --git a/components/soc/esp32c2/include/soc/system_struct.h b/components/soc/esp32c2/include/soc/system_struct.h
index f194474386d..feaa3f1d2e4 100644
--- a/components/soc/esp32c2/include/soc/system_struct.h
+++ b/components/soc/esp32c2/include/soc/system_struct.h
@@ -905,6 +905,7 @@ typedef struct {
     volatile system_reg_date_reg_t reg_date;
 } system_dev_t;
 
+extern system_dev_t SYSTEM;
 
 #ifndef __cplusplus
 _Static_assert(sizeof(system_dev_t) == 0x1000, "Invalid size of system_dev_t structure");
diff --git a/components/soc/esp32c2/ld/esp32c2.peripherals.ld b/components/soc/esp32c2/ld/esp32c2.peripherals.ld
index 11dc6334904..9444bc72eed 100644
--- a/components/soc/esp32c2/ld/esp32c2.peripherals.ld
+++ b/components/soc/esp32c2/ld/esp32c2.peripherals.ld
@@ -20,3 +20,4 @@ PROVIDE ( GPSPI3  = 0x60025000 );
 PROVIDE ( SYSCON = 0x60026000 );
 PROVIDE ( APB_SARADC = 0x60040000 );
 PROVIDE ( GDMA    = 0x6003F000 );
+PROVIDE ( SYSTEM = 0x600c0000 );
diff --git a/components/soc/esp32c3/ld/esp32c3.peripherals.ld b/components/soc/esp32c3/ld/esp32c3.peripherals.ld
index ea6e2ac4195..84de00a603a 100644
--- a/components/soc/esp32c3/ld/esp32c3.peripherals.ld
+++ b/components/soc/esp32c3/ld/esp32c3.peripherals.ld
@@ -33,3 +33,4 @@ PROVIDE ( GPSPI4 = 0x60037000 );
 PROVIDE ( APB_SARADC = 0x60040000 );
 PROVIDE ( USB_SERIAL_JTAG = 0x60043000 );
 PROVIDE ( GDMA    = 0x6003F000 );
+PROVIDE ( SYSTEM = 0x600c0000 );
diff --git a/components/soc/esp32s3/ld/esp32s3.peripherals.ld b/components/soc/esp32s3/ld/esp32s3.peripherals.ld
index 3d69f72f43a..f75bc70beda 100644
--- a/components/soc/esp32s3/ld/esp32s3.peripherals.ld
+++ b/components/soc/esp32s3/ld/esp32s3.peripherals.ld
@@ -49,3 +49,4 @@ PROVIDE ( USB0     = 0x60080000 );
 PROVIDE ( USB_DWC  = 0x60080000 );
 PROVIDE ( USB_WRAP = 0x60039000 );
 PROVIDE ( WORLD_CONTROLLER = 0x600D0000 );
+PROVIDE ( SYSTEM = 0x600C0000 );

From 035c7c145c927fc6cf0ad6e727d92aaf9e1461ce Mon Sep 17 00:00:00 2001
From: morris <maoshengrong@espressif.com>
Date: Mon, 21 Aug 2023 19:14:03 +0800
Subject: [PATCH 3/4] feat(clk_cali): always enable timer group0 for clock
 calibration

Calibration registers are located in the timer group0,
this commit is going to always enable it when the calibration is used by app
---
 .../esp_hw_support/port/esp32/rtc_time.c      | 29 ++++++++++++++++---
 .../esp_hw_support/port/esp32c2/rtc_time.c    | 16 +++++++++-
 .../esp_hw_support/port/esp32c3/rtc_time.c    | 22 +++++++++++---
 .../esp_hw_support/port/esp32c6/rtc_time.c    | 14 +++++++++
 .../esp_hw_support/port/esp32h2/rtc_time.c    | 14 +++++++++
 .../esp_hw_support/port/esp32p4/rtc_time.c    | 16 +++++++++-
 .../esp_hw_support/port/esp32s2/rtc_time.c    | 16 +++++++++-
 .../esp_hw_support/port/esp32s3/rtc_time.c    | 25 ++++++++++++++--
 8 files changed, 139 insertions(+), 13 deletions(-)

diff --git a/components/esp_hw_support/port/esp32/rtc_time.c b/components/esp_hw_support/port/esp32/rtc_time.c
index d24d61e74ce..960d160e912 100644
--- a/components/esp_hw_support/port/esp32/rtc_time.c
+++ b/components/esp_hw_support/port/esp32/rtc_time.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
  */
@@ -8,11 +8,13 @@
 #include "esp_rom_sys.h"
 #include "hal/clk_tree_ll.h"
 #include "hal/rtc_cntl_ll.h"
+#include "hal/timer_ll.h"
 #include "soc/rtc.h"
 #include "soc/timer_periph.h"
 #include "esp_hw_log.h"
+#include "esp_private/periph_ctrl.h"
 
-static const char* TAG = "rtc_time";
+static const char *TAG = "rtc_time";
 
 /* Calibration of RTC_SLOW_CLK is performed using a special feature of TIMG0.
  * This feature counts the number of XTAL clock cycles within a given number of
@@ -55,10 +57,10 @@ static uint32_t rtc_clk_cal_internal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cyc
     uint32_t expected_freq;
     soc_rtc_slow_clk_src_t slow_clk_src = rtc_clk_slow_src_get();
     if (cal_clk == RTC_CAL_32K_XTAL ||
-        (cal_clk == RTC_CAL_RTC_MUX && slow_clk_src == SOC_RTC_SLOW_CLK_SRC_XTAL32K)) {
+            (cal_clk == RTC_CAL_RTC_MUX && slow_clk_src == SOC_RTC_SLOW_CLK_SRC_XTAL32K)) {
         expected_freq = SOC_CLK_XTAL32K_FREQ_APPROX; /* standard 32k XTAL */
     } else if (cal_clk == RTC_CAL_8MD256 ||
-            (cal_clk == RTC_CAL_RTC_MUX && slow_clk_src == SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256)) {
+               (cal_clk == RTC_CAL_RTC_MUX && slow_clk_src == SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256)) {
         expected_freq = SOC_CLK_RC_FAST_D256_FREQ_APPROX;
     } else {
         expected_freq = SOC_CLK_RC_SLOW_FREQ_APPROX; /* 150k internal oscillator */
@@ -185,3 +187,22 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+#ifndef BOOTLOADER_BUILD
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+#else
+    // no critical section is needed for bootloader
+    int __DECLARE_RCC_RC_ATOMIC_ENV;
+    timer_ll_enable_bus_clock(0, true);
+    timer_ll_reset_register(0);
+#endif
+}
diff --git a/components/esp_hw_support/port/esp32c2/rtc_time.c b/components/esp_hw_support/port/esp32c2/rtc_time.c
index 180c51b8bcb..3772b4d4236 100644
--- a/components/esp_hw_support/port/esp32c2/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c2/rtc_time.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,8 +10,10 @@
 #include "soc/rtc_cntl_reg.h"
 #include "hal/clk_tree_ll.h"
 #include "hal/rtc_cntl_ll.h"
+#include "hal/timer_ll.h"
 #include "soc/timer_group_reg.h"
 #include "esp_rom_sys.h"
+#include "esp_private/periph_ctrl.h"
 
 /* Calibration of RTC_SLOW_CLK is performed using a special feature of TIMG0.
  * This feature counts the number of XTAL clock cycles within a given number of
@@ -185,3 +187,15 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+}
diff --git a/components/esp_hw_support/port/esp32c3/rtc_time.c b/components/esp_hw_support/port/esp32c3/rtc_time.c
index aa277ba66c2..ce83921a31a 100644
--- a/components/esp_hw_support/port/esp32c3/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c3/rtc_time.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,8 +10,10 @@
 #include "soc/rtc_cntl_reg.h"
 #include "hal/clk_tree_ll.h"
 #include "hal/rtc_cntl_ll.h"
+#include "hal/timer_ll.h"
 #include "soc/timer_group_reg.h"
 #include "esp_rom_sys.h"
+#include "esp_private/periph_ctrl.h"
 
 /* Calibration of RTC_SLOW_CLK is performed using a special feature of TIMG0.
  * This feature counts the number of XTAL clock cycles within a given number of
@@ -49,7 +51,6 @@ uint32_t rtc_clk_cal_internal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles)
         cal_clk = RTC_CAL_RTC_MUX;
     }
 
-
     /* Enable requested clock (150k clock is always on) */
     bool dig_32k_xtal_enabled = clk_ll_xtal32k_digi_is_enabled();
     if (cal_clk == RTC_CAL_32K_XTAL && !dig_32k_xtal_enabled) {
@@ -72,7 +73,7 @@ uint32_t rtc_clk_cal_internal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles)
          */
         REG_SET_FIELD(TIMG_RTCCALICFG2_REG(0), TIMG_RTC_CALI_TIMEOUT_THRES, 1);
         while (!GET_PERI_REG_MASK(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_RDY)
-               && !GET_PERI_REG_MASK(TIMG_RTCCALICFG2_REG(0), TIMG_RTC_CALI_TIMEOUT));
+                && !GET_PERI_REG_MASK(TIMG_RTCCALICFG2_REG(0), TIMG_RTC_CALI_TIMEOUT));
     }
 
     /* Prepare calibration */
@@ -146,8 +147,9 @@ uint32_t rtc_clk_cal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles)
     rtc_xtal_freq_t xtal_freq = rtc_clk_xtal_freq_get();
     uint64_t xtal_cycles = rtc_clk_cal_internal(cal_clk, slowclk_cycles);
 
-    if ((cal_clk == RTC_CAL_32K_XTAL) && !rtc_clk_cal_32k_valid(xtal_freq, slowclk_cycles, xtal_cycles))
+    if ((cal_clk == RTC_CAL_32K_XTAL) && !rtc_clk_cal_32k_valid(xtal_freq, slowclk_cycles, xtal_cycles)) {
         return 0;
+    }
 
     uint64_t divider = ((uint64_t)xtal_freq) * slowclk_cycles;
     uint64_t period_64 = ((xtal_cycles << RTC_CLK_CAL_FRACT) + divider / 2 - 1) / divider;
@@ -188,3 +190,15 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+}
diff --git a/components/esp_hw_support/port/esp32c6/rtc_time.c b/components/esp_hw_support/port/esp32c6/rtc_time.c
index f662965f1ec..06ef4967381 100644
--- a/components/esp_hw_support/port/esp32c6/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c6/rtc_time.c
@@ -10,11 +10,13 @@
 #include "soc/lp_timer_reg.h"
 #include "hal/lp_timer_hal.h"
 #include "hal/clk_tree_ll.h"
+#include "hal/timer_ll.h"
 #include "soc/timer_group_reg.h"
 #include "esp_rom_sys.h"
 #include "assert.h"
 #include "hal/efuse_hal.h"
 #include "soc/chip_revision.h"
+#include "esp_private/periph_ctrl.h"
 
 static const char *TAG = "rtc_time";
 
@@ -262,3 +264,15 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+}
diff --git a/components/esp_hw_support/port/esp32h2/rtc_time.c b/components/esp_hw_support/port/esp32h2/rtc_time.c
index 75bc12348be..e3b421b25bf 100644
--- a/components/esp_hw_support/port/esp32h2/rtc_time.c
+++ b/components/esp_hw_support/port/esp32h2/rtc_time.c
@@ -9,11 +9,13 @@
 #include "soc/rtc.h"
 #include "soc/lp_timer_reg.h"
 #include "hal/clk_tree_ll.h"
+#include "hal/timer_ll.h"
 #include "soc/timer_group_reg.h"
 #include "esp_rom_sys.h"
 #include "assert.h"
 #include "hal/efuse_hal.h"
 #include "soc/chip_revision.h"
+#include "esp_private/periph_ctrl.h"
 
 static const char *TAG = "rtc_time";
 
@@ -264,3 +266,15 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+}
diff --git a/components/esp_hw_support/port/esp32p4/rtc_time.c b/components/esp_hw_support/port/esp32p4/rtc_time.c
index 427fe139d8b..95075cedf27 100644
--- a/components/esp_hw_support/port/esp32p4/rtc_time.c
+++ b/components/esp_hw_support/port/esp32p4/rtc_time.c
@@ -5,14 +5,16 @@
  */
 
 #include <stdint.h>
+#include <assert.h>
 #include "esp32p4/rom/ets_sys.h"
 #include "soc/rtc.h"
 #include "soc/lp_timer_reg.h"
 #include "hal/lp_timer_hal.h"
 #include "hal/clk_tree_ll.h"
+#include "hal/timer_ll.h"
 #include "soc/timer_group_reg.h"
 #include "esp_rom_sys.h"
-#include "assert.h"
+#include "esp_private/periph_ctrl.h"
 
 static const char *TAG = "rtc_time";
 
@@ -225,3 +227,15 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+}
diff --git a/components/esp_hw_support/port/esp32s2/rtc_time.c b/components/esp_hw_support/port/esp32s2/rtc_time.c
index aae694037e4..506dd63a6f2 100644
--- a/components/esp_hw_support/port/esp32s2/rtc_time.c
+++ b/components/esp_hw_support/port/esp32s2/rtc_time.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,7 +10,9 @@
 #include "soc/rtc_cntl_reg.h"
 #include "hal/clk_tree_ll.h"
 #include "hal/rtc_cntl_ll.h"
+#include "hal/timer_ll.h"
 #include "soc/timer_group_reg.h"
+#include "esp_private/periph_ctrl.h"
 
 /* Calibration of RTC_SLOW_CLK is performed using a special feature of TIMG0.
  * This feature counts the number of XTAL clock cycles within a given number of
@@ -253,3 +255,15 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+}
diff --git a/components/esp_hw_support/port/esp32s3/rtc_time.c b/components/esp_hw_support/port/esp32s3/rtc_time.c
index ff58ed4d71d..f719c14a8ad 100644
--- a/components/esp_hw_support/port/esp32s3/rtc_time.c
+++ b/components/esp_hw_support/port/esp32s3/rtc_time.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -9,8 +9,10 @@
 #include "soc/rtc.h"
 #include "soc/rtc_cntl_reg.h"
 #include "hal/clk_tree_ll.h"
+#include "hal/timer_ll.h"
 #include "hal/rtc_cntl_ll.h"
 #include "soc/timer_group_reg.h"
+#include "esp_private/periph_ctrl.h"
 
 /* Calibration of RTC_SLOW_CLK is performed using a special feature of TIMG0.
  * This feature counts the number of XTAL clock cycles within a given number of
@@ -70,7 +72,7 @@ uint32_t rtc_clk_cal_internal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles)
          */
         REG_SET_FIELD(TIMG_RTCCALICFG2_REG(0), TIMG_RTC_CALI_TIMEOUT_THRES, 1);
         while (!GET_PERI_REG_MASK(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_RDY)
-               && !GET_PERI_REG_MASK(TIMG_RTCCALICFG2_REG(0), TIMG_RTC_CALI_TIMEOUT));
+                && !GET_PERI_REG_MASK(TIMG_RTCCALICFG2_REG(0), TIMG_RTC_CALI_TIMEOUT));
     }
 
     /* Prepare calibration */
@@ -187,3 +189,22 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     }
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
+
+/// @brief if the calibration is used, we need to enable the timer group0 first
+__attribute__((constructor))
+static void enable_timer_group0_for_calibration(void)
+{
+#ifndef BOOTLOADER_BUILD
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+#else
+    // no critical section is needed for bootloader
+    int __DECLARE_RCC_RC_ATOMIC_ENV;
+    timer_ll_enable_bus_clock(0, true);
+    timer_ll_reset_register(0);
+#endif
+}

From 4e143adf9de81af9e3428a17609808c6c4fd2ee3 Mon Sep 17 00:00:00 2001
From: morris <maoshengrong@espressif.com>
Date: Tue, 22 Aug 2023 16:50:53 +0800
Subject: [PATCH 4/4] docs(hal): update readme about the usage of the RCC
 macros

---
 components/hal/README.md             | 72 ++++++++++++++++++++++++----
 components/hal/include/hal/readme.md | 25 ----------
 2 files changed, 64 insertions(+), 33 deletions(-)
 delete mode 100644 components/hal/include/hal/readme.md

diff --git a/components/hal/README.md b/components/hal/README.md
index 71f0e742569..7ec82ff77d2 100644
--- a/components/hal/README.md
+++ b/components/hal/README.md
@@ -1,19 +1,75 @@
-## `hal`
+# `hal` (G0 component)
 
-The `hal` component provides hardware abstraction and implementation for targets supported by ESP-IDF.
+⚠️ The HAL component is still under heavy development at the moment, so we don't guarantee the stability and backward-compatibility among versions.
 
-#### `include/hal`
+The `hal` component provides a **Hardware Abstraction Layer** for all targets supported by ESP-IDF. It is designed to be a `G0` component so that it can be used by other components like `driver`, `esp_hw_support`, `esp_system` and so on.
+
+In a broad sense, the HAL layer consists of two sub-layers: HAL (upper) and Low-Level(bottom). The HAL layer defines the steps and data that is required to operate a peripheral (e.g. initialization, start and stop). The low-level is a translation layer above the register files under the `soc` component, it only covers general conceptions to register configurations.
+
+## Low-Level (`hal/<periph>_ll.h`)
+
+Functions defined in the file must be static inlined. The first argument of an LL function is usually a pointer to the peripheral's base address [^1]. At the moment, each ESP target has its own set of Low-Level drivers. They're located under path e.g. `components/hal/<target>/include/hal/<periph>_ll.h`. We wish the the low-level functions could be as independent as possible, so that the caller doesn't need to worry about conflict between different sub-modules. For example, when resetting the driver of module A, the module B is also reset by accident. However, the digital design is not perfect, coupling happens from time to time.
+
+### Handling Shared Registers
+
+One of the biggest coupling is the so-called "hardware shared resource". Take the common `Reset and Clock Control` part as an example, the clock enable and disable logic of different peripherals are mixing in the same register. In RTOS environment, it's super easy to make a mistake when you enable peripheral A and then peripheral B is disabled by accident. A simple way to avoid such mistake is to using a critical section when accessing such shared registers. However from the point of the software architecture, it's not a good idea to add a **lock** in the Low-Level because it's a concept of the operating system.
+
+One compromise is to **highlight** the LL function which needs the caller to use them in a critical section. e.g.
+
+```c
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timer_ll_reset_register(...) (void)__DECLARE_RCC_RC_ATOMIC_ENV; timer_ll_reset_register(__VA_ARGS__)
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_ATOMIC_ENV variable in advance
+#define timer_ll_set_clock_source(...) (void)__DECLARE_RCC_ATOMIC_ENV; timer_ll_set_clock_source(__VA_ARGS__)
+```
+
+By referencing a variable which is only declared in the critical section, the compiler will report an error if the caller forgets to use the critical section. The following macros are provided by `esp_private/periph_ctrl.h`, which contain the above *magic* variables.
+
+| Macro | Private variables used to declare a critical section | Use condition |
+| --- | --- | --- |
+| `PERIPH_RCC_ACQUIRE_ATOMIC` | *__DECLARE_RCC_RC_ATOMIC_ENV* | This critical section not only protects the shared register accessing, but also **increases** a reference counter of the peripheral module. </br> You should use this critical section if the peripheral module has multiple independent sub-modules. |
+| `PERIPH_RCC_RELEASE_ATOMIC` | *__DECLARE_RCC_RC_ATOMIC_ENV* | This critical section not only protects the shared register accessing, but also **decreases** a reference counter of the peripheral module. </br> You should use this critical section if the peripheral module has multiple independent sub-modules. |
+| `PERIPH_RCC_ATOMIC` | *__DECLARE_RCC_ATOMIC_ENV* | This critical section only protects the shared register accessing. |
+
+ESP-IDF driver developers then can use the above macros to call the special LL functions. e.g.
+
+```c
+static void enable_timer_group0_for_calibration(void)
+{
+    PERIPH_RCC_ACQUIRE_ATOMIC(PERIPH_TIMG0_MODULE, ref_count) {
+        if (ref_count == 0) {
+            timer_ll_enable_bus_clock(0, true);
+            timer_ll_reset_register(0);
+        }
+    }
+}
+```
+
+## HAL (`hal/<periph>_hal.h`)
+
+This layer is a combination of Low-Level function calls, aiming to ease the load when porting a new chip to other platforms (e.g. Zephyr). This layer shouldn't rely on Operating System, i.e., don't use primitives that only offered by an Operating System, e.g., the lock and other blocking functions. Please don't introduce any *driver models* in the HAL layer so that the non-idf developers can customized their own drivers according to their platform requirement.
+
+The first argument of a HAL function is usually a pointer to the **context object**. The context object is a structure which saves the necessary information that is used by the HAL driver (e.g. the base address of the peripheral). ⚡ Please note, the memory used by the HAL context object is allocated by the caller, so the HAL driver shouldn't free it.
+
+## File Structure
+
+### `include/hal`
 
 `/include/hal` contains header files which provides a hardware-agnostic interface to the SoC. The interface consists of function declarations and abstracted types that other, higher level components can make use of in order to have code portable to all targets ESP-IDF supports.
 
-It contains an abstraction layer for ineracting with/driving the hardware found in the SoC such as the peripherals and 'core' hardware such as the CPU, MPU, caches, etc. It contains for the abstracted types.
-The abstraction design is actually two levels -- often somtimes `xxx_hal.h` includes a lower-level header from a `xxx_ll.h`,  which resides in the implementation. More on this abstraction design in the [`hal/include/hal`'s Readme](include/hal/readme.md)
+It contains an abstraction layer for interacting with/driving the hardware found in the SoC such as the peripherals and 'core' hardware such as the CPU, MPU, caches, etc. It contains for the abstracted types.
+The abstraction design is actually two levels -- often sometimes `xxx_hal.h` includes a lower-level header from a `xxx_ll.h`,  which resides in the implementation. More on this abstraction design in the [`hal/include/hal`'s Readme](include/hal/readme.md)
 
-#### `target/include`
+### `target/include`
 
-Provides the implementation of the hardware-agnostic interface in the abstraction. Target-specific subdirectories exist for wildly different implementations among targets; while code that are common/very similar might be placed in the top-level of `/<target>/include`, using some amount of conditional preprocessors. It is up to the developers' discretion on which strategy to use. Code usually reside in source files with same names to header files whose interfaces they implement, ex. `xxx_hal.c` for `xxx_hal.h`.
+Provides the implementation of the hardware-agnostic interface in the abstraction. Target-specific subdirectories exist for wildly different implementations among targets; while code that are common/very similar might be placed in the top-level of `/<target>/include`, using some amount of conditional preprocessor. It is up to the developers' discretion on which strategy to use. Code usually reside in source files with same names to header files whose interfaces they implement, ex. `xxx_hal.c` for `xxx_hal.h`.
 
 As mentioned previously, the lower-level abstraction header `xxx_ll.h` resides in this directory, since they contain hardware-specific details.
 However, what these can do is provide some abstraction among implementations, so that more code can be moved to the common, non-target-specific subdirectories.
 
-This can also contain target-specific extensions to the HAL headers. These target-specific HAL headers have the same name and include the abstraction layer HAL header via `include_next`. These extensions might add more function declarations or override some things using macro magic.
\ No newline at end of file
+This can also contain target-specific extensions to the HAL headers. These target-specific HAL headers have the same name and include the abstraction layer HAL header via `include_next`. These extensions might add more function declarations or override some things using macro magic.
+
+[^1]: This is not a must. Sometimes if the LL is just operating some system level registers, you don't have to provide this argument.
diff --git a/components/hal/include/hal/readme.md b/components/hal/include/hal/readme.md
deleted file mode 100644
index 17ee6b2c6c9..00000000000
--- a/components/hal/include/hal/readme.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# HAL Layer Readme
-
-The HAL layer is designed to be used by the drivers. We don't guarantee the stability and back-compatibility among
-versions. The HAL layer may update very frequently with the driver. Please don't use them in the applications or treat
-them as stable APIs.
-
-The HAL layer consists of two layers: HAL (upper) and Lowlevel(bottom). The HAL layer defines the steps and data
-required by the peripheral. The lowlevel is a translation layer converting general conceptions to register configurations.
-
-## Lowlevel
-
-This layer should be all static inline. The first argument of LL functions is usually a pointer to the beginning address
-of the peripheral register. Each chip should have its own LL layer. The functions in this layer should be atomic and
-independent from each other so that the upper layer can change/perform one of the options/operation without touching the
-others.
-
-## HAL
-
-This layer should depend on the operating system as little as possible. It's a wrapping of LL functions, so that the upper
-layer can combine basic steps into different working ways (polling, non-polling, interrupt, etc.). Without using
-queues/locks/delay/loop/etc., this layer can be easily port to other os or simulation systems.
-
-To get better performance and better porting ability, ``context``s are used to hold sustainable data and pass the parameters.
-
-To develop your own driver, it is suggested to copy the HAL layer to your own code and keep them until manual update.