From fe939208c3f2ad5ea8521ac29744a92d2a3d0a0d 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/rtc_time.c   | 2 ++
 components/esp_hw_support/port/esp32c2/rtc_time.c | 2 ++
 components/esp_hw_support/port/esp32c3/rtc_time.c | 2 ++
 components/esp_hw_support/port/esp32c6/rtc_time.c | 2 ++
 components/esp_hw_support/port/esp32h2/rtc_time.c | 2 ++
 components/esp_hw_support/port/esp32p4/rtc_time.c | 2 ++
 components/esp_hw_support/port/esp32s2/rtc_time.c | 2 ++
 components/esp_hw_support/port/esp32s3/rtc_time.c | 2 ++
 components/soc/esp32/include/soc/rtc.h            | 8 ++++++++
 components/soc/esp32c2/include/soc/rtc.h          | 8 ++++++++
 components/soc/esp32c3/include/soc/rtc.h          | 8 ++++++++
 components/soc/esp32c6/include/soc/rtc.h          | 8 ++++++++
 components/soc/esp32h2/include/soc/rtc.h          | 8 ++++++++
 components/soc/esp32p4/include/soc/rtc.h          | 8 ++++++++
 components/soc/esp32s2/include/soc/rtc.h          | 8 ++++++++
 components/soc/esp32s3/include/soc/rtc.h          | 8 ++++++++
 16 files changed, 80 insertions(+)

diff --git a/components/esp_hw_support/port/esp32/rtc_time.c b/components/esp_hw_support/port/esp32/rtc_time.c
index 528aa549ad..5b5c4598c3 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/rtc_time.c b/components/esp_hw_support/port/esp32c2/rtc_time.c
index acae81a813..8c8ac2016b 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/rtc_time.c b/components/esp_hw_support/port/esp32c3/rtc_time.c
index d31209b0c9..17cacbbb70 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/esp32c6/rtc_time.c b/components/esp_hw_support/port/esp32c6/rtc_time.c
index b215e0f948..d5ad37cc7b 100644
--- a/components/esp_hw_support/port/esp32c6/rtc_time.c
+++ b/components/esp_hw_support/port/esp32c6/rtc_time.c
@@ -267,6 +267,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/rtc_time.c b/components/esp_hw_support/port/esp32h2/rtc_time.c
index 306fe4e307..2bf4e6ed9b 100644
--- a/components/esp_hw_support/port/esp32h2/rtc_time.c
+++ b/components/esp_hw_support/port/esp32h2/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/esp32p4/rtc_time.c b/components/esp_hw_support/port/esp32p4/rtc_time.c
index 3eb3253cd7..483ecc54d6 100644
--- a/components/esp_hw_support/port/esp32p4/rtc_time.c
+++ b/components/esp_hw_support/port/esp32p4/rtc_time.c
@@ -230,6 +230,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/rtc_time.c b/components/esp_hw_support/port/esp32s2/rtc_time.c
index 3818a2624a..4df6a05180 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/rtc_time.c b/components/esp_hw_support/port/esp32s3/rtc_time.c
index c161e57d1e..32bb0796fc 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)
diff --git a/components/soc/esp32/include/soc/rtc.h b/components/soc/esp32/include/soc/rtc.h
index efa692d6fe..a712d5fb1a 100644
--- a/components/soc/esp32/include/soc/rtc.h
+++ b/components/soc/esp32/include/soc/rtc.h
@@ -488,6 +488,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/soc/esp32c2/include/soc/rtc.h b/components/soc/esp32c2/include/soc/rtc.h
index d8b3c1897c..3ea2f23fbb 100644
--- a/components/soc/esp32c2/include/soc/rtc.h
+++ b/components/soc/esp32c2/include/soc/rtc.h
@@ -514,6 +514,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/soc/esp32c3/include/soc/rtc.h b/components/soc/esp32c3/include/soc/rtc.h
index 3e91b64bbf..165f8b957e 100644
--- a/components/soc/esp32c3/include/soc/rtc.h
+++ b/components/soc/esp32c3/include/soc/rtc.h
@@ -541,6 +541,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/soc/esp32c6/include/soc/rtc.h b/components/soc/esp32c6/include/soc/rtc.h
index 46fb2c978a..4a9a984080 100644
--- a/components/soc/esp32c6/include/soc/rtc.h
+++ b/components/soc/esp32c6/include/soc/rtc.h
@@ -486,6 +486,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/soc/esp32h2/include/soc/rtc.h b/components/soc/esp32h2/include/soc/rtc.h
index 3c6010db02..4a7f34885f 100644
--- a/components/soc/esp32h2/include/soc/rtc.h
+++ b/components/soc/esp32h2/include/soc/rtc.h
@@ -482,6 +482,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/soc/esp32p4/include/soc/rtc.h b/components/soc/esp32p4/include/soc/rtc.h
index 558b033b1d..5558cd2f43 100644
--- a/components/soc/esp32p4/include/soc/rtc.h
+++ b/components/soc/esp32p4/include/soc/rtc.h
@@ -567,6 +567,14 @@ typedef soc_rtc_fast_clk_src_t rtc_fast_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/soc/esp32s2/include/soc/rtc.h b/components/soc/esp32s2/include/soc/rtc.h
index 3a333fa379..ad92d0fee9 100644
--- a/components/soc/esp32s2/include/soc/rtc.h
+++ b/components/soc/esp32s2/include/soc/rtc.h
@@ -574,6 +574,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/soc/esp32s3/include/soc/rtc.h b/components/soc/esp32s3/include/soc/rtc.h
index e1b34178ba..52b46071d2 100644
--- a/components/soc/esp32s3/include/soc/rtc.h
+++ b/components/soc/esp32s3/include/soc/rtc.h
@@ -554,6 +554,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
  */