From 03ba1cfb8b95425e03c6899a8cad2561c279c69a Mon Sep 17 00:00:00 2001
From: Li Shuai <lishuai@espressif.com>
Date: Tue, 1 Apr 2025 19:16:17 +0800
Subject: [PATCH] change(esp_hw_support): add interface to calculate slow clock
 period by clock frequency

---
 components/esp_hw_support/port/esp32/include/soc/rtc.h    | 8 ++++++++
 components/esp_hw_support/port/esp32/rtc_time.c           | 2 ++
 components/esp_hw_support/port/esp32c2/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32c2/rtc_time.c         | 2 ++
 components/esp_hw_support/port/esp32c3/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32c3/rtc_time.c         | 2 ++
 components/esp_hw_support/port/esp32c5/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32c5/rtc_time.c         | 2 ++
 components/esp_hw_support/port/esp32c6/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32c6/rtc_time.c         | 2 ++
 components/esp_hw_support/port/esp32c61/include/soc/rtc.h | 8 ++++++++
 components/esp_hw_support/port/esp32c61/rtc_time.c        | 2 ++
 components/esp_hw_support/port/esp32h2/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32h2/rtc_time.c         | 2 ++
 components/esp_hw_support/port/esp32p4/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32p4/rtc_time.c         | 2 ++
 components/esp_hw_support/port/esp32s2/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32s2/rtc_time.c         | 2 ++
 components/esp_hw_support/port/esp32s3/include/soc/rtc.h  | 8 ++++++++
 components/esp_hw_support/port/esp32s3/rtc_time.c         | 2 ++
 20 files changed, 100 insertions(+)

diff --git a/components/esp_hw_support/port/esp32/include/soc/rtc.h b/components/esp_hw_support/port/esp32/include/soc/rtc.h
index 69b152143f..234783e9a6 100644
--- a/components/esp_hw_support/port/esp32/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32/include/soc/rtc.h
@@ -478,6 +478,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 /**
  * @brief sleep configuration for rtc_sleep_init function
  */
diff --git a/components/esp_hw_support/port/esp32/rtc_time.c b/components/esp_hw_support/port/esp32/rtc_time.c
index 447c109ec8..03695fc93c 100644
--- a/components/esp_hw_support/port/esp32/rtc_time.c
+++ b/components/esp_hw_support/port/esp32/rtc_time.c
@@ -191,6 +191,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32c2/include/soc/rtc.h b/components/esp_hw_support/port/esp32c2/include/soc/rtc.h
index 0cc79431c0..0269caa4e0 100644
--- a/components/esp_hw_support/port/esp32c2/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32c2/include/soc/rtc.h
@@ -508,6 +508,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 /**
  * @brief Power down flags for rtc_sleep_pd function
  */
diff --git a/components/esp_hw_support/port/esp32c2/rtc_time.c b/components/esp_hw_support/port/esp32c2/rtc_time.c
index 5c7470dad4..d724df17a1 100644
--- a/components/esp_hw_support/port/esp32c2/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c2/rtc_time.c
@@ -191,6 +191,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32c3/include/soc/rtc.h b/components/esp_hw_support/port/esp32c3/include/soc/rtc.h
index c160b128f4..bb60f57d5a 100644
--- a/components/esp_hw_support/port/esp32c3/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32c3/include/soc/rtc.h
@@ -536,6 +536,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 /**
  * @brief Power down flags for rtc_sleep_pd function
  */
diff --git a/components/esp_hw_support/port/esp32c3/rtc_time.c b/components/esp_hw_support/port/esp32c3/rtc_time.c
index bf1aa97259..783aa93ffb 100644
--- a/components/esp_hw_support/port/esp32c3/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c3/rtc_time.c
@@ -194,6 +194,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32c5/include/soc/rtc.h b/components/esp_hw_support/port/esp32c5/include/soc/rtc.h
index a4e00edfdf..a111c411db 100644
--- a/components/esp_hw_support/port/esp32c5/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32c5/include/soc/rtc.h
@@ -469,6 +469,14 @@ typedef soc_xtal_freq_t rtc_xtal_freq_t;
 #define RTC_XTAL_FREQ_40M SOC_XTAL_FREQ_40M                 //!< 40 MHz XTAL
 #define RTC_XTAL_FREQ_48M SOC_XTAL_FREQ_48M                 //!< 48 MHz XTAL
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/components/esp_hw_support/port/esp32c5/rtc_time.c b/components/esp_hw_support/port/esp32c5/rtc_time.c
index 4e260b2389..15a6f5873d 100644
--- a/components/esp_hw_support/port/esp32c5/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c5/rtc_time.c
@@ -269,6 +269,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32c6/include/soc/rtc.h b/components/esp_hw_support/port/esp32c6/include/soc/rtc.h
index 2041422b49..404d0d68a9 100644
--- a/components/esp_hw_support/port/esp32c6/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32c6/include/soc/rtc.h
@@ -456,6 +456,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 
 // -------------------------- CLOCK TREE DEFS ALIAS ----------------------------
 // **WARNING**: The following are only for backwards compatibility.
diff --git a/components/esp_hw_support/port/esp32c6/rtc_time.c b/components/esp_hw_support/port/esp32c6/rtc_time.c
index a2393ec04a..917eb6cc2f 100644
--- a/components/esp_hw_support/port/esp32c6/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c6/rtc_time.c
@@ -271,6 +271,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32c61/include/soc/rtc.h b/components/esp_hw_support/port/esp32c61/include/soc/rtc.h
index 2f8ac74bfd..c17f22255b 100644
--- a/components/esp_hw_support/port/esp32c61/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32c61/include/soc/rtc.h
@@ -495,6 +495,14 @@ typedef soc_xtal_freq_t rtc_xtal_freq_t;
 #define rtc_clk_fast_freq_set(fast_freq) rtc_clk_fast_src_set(fast_freq)
 #define rtc_clk_fast_freq_get() rtc_clk_fast_src_get()
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/components/esp_hw_support/port/esp32c61/rtc_time.c b/components/esp_hw_support/port/esp32c61/rtc_time.c
index 688b777334..560e8f56a0 100644
--- a/components/esp_hw_support/port/esp32c61/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c61/rtc_time.c
@@ -268,6 +268,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32h2/include/soc/rtc.h b/components/esp_hw_support/port/esp32h2/include/soc/rtc.h
index d429e5d611..8497ed8b9f 100644
--- a/components/esp_hw_support/port/esp32h2/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32h2/include/soc/rtc.h
@@ -454,6 +454,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 // -------------------------- CLOCK TREE DEFS ALIAS ----------------------------
 // **WARNING**: The following are only for backwards compatibility.
 // Please use the declarations in soc/clk_tree_defs.h instead.
diff --git a/components/esp_hw_support/port/esp32h2/rtc_time.c b/components/esp_hw_support/port/esp32h2/rtc_time.c
index ccd3dc491f..c682832eca 100644
--- a/components/esp_hw_support/port/esp32h2/rtc_time.c
+++ b/components/esp_hw_support/port/esp32h2/rtc_time.c
@@ -271,6 +271,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32p4/include/soc/rtc.h b/components/esp_hw_support/port/esp32p4/include/soc/rtc.h
index df86bffa5a..940409df6c 100644
--- a/components/esp_hw_support/port/esp32p4/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32p4/include/soc/rtc.h
@@ -469,6 +469,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 /**
  * @brief Enable or disable APLL
  *
diff --git a/components/esp_hw_support/port/esp32p4/rtc_time.c b/components/esp_hw_support/port/esp32p4/rtc_time.c
index d7a9cf5bab..8c5a526233 100644
--- a/components/esp_hw_support/port/esp32p4/rtc_time.c
+++ b/components/esp_hw_support/port/esp32p4/rtc_time.c
@@ -228,6 +228,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32s2/include/soc/rtc.h b/components/esp_hw_support/port/esp32s2/include/soc/rtc.h
index 08dcc1ca19..c173e99926 100644
--- a/components/esp_hw_support/port/esp32s2/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32s2/include/soc/rtc.h
@@ -569,6 +569,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 /**
  * @brief Power down flags for rtc_sleep_pd function
  */
diff --git a/components/esp_hw_support/port/esp32s2/rtc_time.c b/components/esp_hw_support/port/esp32s2/rtc_time.c
index 76df279092..39e59e56a1 100644
--- a/components/esp_hw_support/port/esp32s2/rtc_time.c
+++ b/components/esp_hw_support/port/esp32s2/rtc_time.c
@@ -259,6 +259,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)
diff --git a/components/esp_hw_support/port/esp32s3/include/soc/rtc.h b/components/esp_hw_support/port/esp32s3/include/soc/rtc.h
index 7c503c7f5a..5df4d082d0 100644
--- a/components/esp_hw_support/port/esp32s3/include/soc/rtc.h
+++ b/components/esp_hw_support/port/esp32s3/include/soc/rtc.h
@@ -547,6 +547,14 @@ bool rtc_dig_8m_enabled(void);
  */
 uint32_t rtc_clk_freq_cal(uint32_t cal_val);
 
+/**
+ * @brief Calculate the slow clock period value by slow clock frequency
+ *
+ * @param freq_hz Frequency of the slow clock in Hz
+ * @return Fixed point value of slow clock period in microseconds
+ */
+uint32_t rtc_clk_freq_to_period(uint32_t freq_hz);
+
 /**
  * @brief Power up flags for rtc_sleep_pd function
  */
diff --git a/components/esp_hw_support/port/esp32s3/rtc_time.c b/components/esp_hw_support/port/esp32s3/rtc_time.c
index 834676a880..4b78096c5c 100644
--- a/components/esp_hw_support/port/esp32s3/rtc_time.c
+++ b/components/esp_hw_support/port/esp32s3/rtc_time.c
@@ -193,6 +193,8 @@ uint32_t rtc_clk_freq_cal(uint32_t cal_val)
     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
 }
 
+uint32_t rtc_clk_freq_to_period(uint32_t) __attribute__((alias("rtc_clk_freq_cal")));
+
 /// @brief if the calibration is used, we need to enable the timer group0 first
 __attribute__((constructor))
 static void enable_timer_group0_for_calibration(void)