Merge branch 'bugfix/warn_rc32k_use_in_kconfig' into 'master'

songruo · songruo · commit 8771607562d3 · 2024-11-28T14:58:16.000+08:00
fix(clk): add an inevitable kconfig option to be selected to use rc32k

See merge request espressif/esp-idf!34417
diff --git a/components/esp_hw_support/CMakeLists.txt b/components/esp_hw_support/CMakeLists.txt
@@ -18,10 +18,6 @@ if(${target} STREQUAL "esp32c6")
     list(APPEND priv_requires hal)
 endif()
 
-if(CONFIG_RTC_CLK_SRC_INT_RC32K)
-    message(WARNING "Internal RC32K clock is unstable at extreme temperatures and is not recommended for use.")
-endif()
-
 set(srcs "cpu.c" "port/${IDF_TARGET}/esp_cpu_intr.c" "esp_memory_utils.c" "port/${IDF_TARGET}/cpu_region_protect.c")
 if(NOT non_os_build)
     list(APPEND srcs "esp_clk.c"
diff --git a/components/esp_hw_support/port/esp32c6/Kconfig.rtc b/components/esp_hw_support/port/esp32c6/Kconfig.rtc
@@ -13,12 +13,18 @@ choice RTC_CLK_SRC
         bool "External 32 kHz oscillator at 32K_XP pin"
         select ESP_SYSTEM_RTC_EXT_OSC
     config RTC_CLK_SRC_INT_RC32K
-        bool "Internal 32 kHz RC oscillator"
+        bool "Internal 32 kHz RC oscillator (NOT RECOMMENDED TO USE, READ DOCS FIRST)"
+        depends on RTC_CLK_SRC_USE_DANGEROUS_RC32K_ALLOWED
         help
-            Internal RC32K clock is unstable at extreme temperatures and is not recommended for use.
+            To be able to select this option, please select `RTC_CLK_SRC_USE_DANGEROUS_RC32K_ALLOWED` first.
             This option will be removed in IDF v6.0.
 endchoice
 
+config RTC_CLK_SRC_USE_DANGEROUS_RC32K_ALLOWED
+    bool "Confirm to use the unrecommended 32 kHz RC oscillator (READ DOCS FIRST)"
+    help
+        Internal RC32K clock is unstable at extreme temperatures and is not recommended for use.
+
 config RTC_CLK_CAL_CYCLES
     int "Number of cycles for RTC_SLOW_CLK calibration"
     default 3000 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_EXT_OSC || RTC_CLK_SRC_INT_RC32K
diff --git a/components/esp_hw_support/port/esp32h2/Kconfig.rtc b/components/esp_hw_support/port/esp32h2/Kconfig.rtc
@@ -12,18 +12,13 @@ choice RTC_CLK_SRC
     config RTC_CLK_SRC_EXT_OSC
         bool "External 32 kHz oscillator at 32K_XP pin"
         select ESP_SYSTEM_RTC_EXT_OSC
-    config RTC_CLK_SRC_INT_RC32K
-        bool "Internal 32 kHz RC oscillator"
-        help
-            Internal RC32K clock is unstable at extreme temperatures and is not recommended for use.
-            This option will be removed in IDF v6.0.
 endchoice
 
 config RTC_CLK_CAL_CYCLES
     int "Number of cycles for RTC_SLOW_CLK calibration"
-    default 3000 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_EXT_OSC || RTC_CLK_SRC_INT_RC32K
+    default 3000 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_EXT_OSC
     default 1024 if RTC_CLK_SRC_INT_RC
-    range 0 8190 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_EXT_OSC || RTC_CLK_SRC_INT_RC32K
+    range 0 8190 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_EXT_OSC
     range 0 32766 if RTC_CLK_SRC_INT_RC
     help
         When the startup code initializes RTC_SLOW_CLK, it can perform
diff --git a/components/esp_hw_support/port/esp32p4/Kconfig.rtc b/components/esp_hw_support/port/esp32p4/Kconfig.rtc
@@ -9,18 +9,13 @@ choice RTC_CLK_SRC
     config RTC_CLK_SRC_EXT_CRYS
         bool "External 32 kHz crystal"
         select ESP_SYSTEM_RTC_EXT_XTAL
-    config RTC_CLK_SRC_INT_RC32K
-        bool "Internal 32 kHz RC oscillator"
-        help
-            Internal RC32K clock is unstable at extreme temperatures and is not recommended for use.
-            This option will be removed in IDF v6.0.
 endchoice
 
 config RTC_CLK_CAL_CYCLES
     int "Number of cycles for RTC_SLOW_CLK calibration"
-    default 3000 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_INT_RC32K
+    default 3000 if RTC_CLK_SRC_EXT_CRYS
     default 1024 if RTC_CLK_SRC_INT_RC
-    range 0 8190 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_INT_RC32K
+    range 0 8190 if RTC_CLK_SRC_EXT_CRYS
     range 0 32766 if RTC_CLK_SRC_INT_RC
     help
         When the startup code initializes RTC_SLOW_CLK, it can perform
diff --git a/components/esp_system/port/soc/esp32h2/clk.c b/components/esp_system/port/soc/esp32h2/clk.c
@@ -107,8 +107,6 @@ __attribute__((weak)) void esp_clk_init(void)
     select_rtc_slow_clk(SOC_RTC_SLOW_CLK_SRC_XTAL32K);
 #elif defined(CONFIG_RTC_CLK_SRC_EXT_OSC)
     select_rtc_slow_clk(SOC_RTC_SLOW_CLK_SRC_OSC_SLOW);
-#elif defined(CONFIG_RTC_CLK_SRC_INT_RC32K)
-    select_rtc_slow_clk(SOC_RTC_SLOW_CLK_SRC_RC32K);
 #else
     select_rtc_slow_clk(SOC_RTC_SLOW_CLK_SRC_RC_SLOW);
 #endif
diff --git a/components/esp_system/port/soc/esp32p4/clk.c b/components/esp_system/port/soc/esp32p4/clk.c
@@ -114,8 +114,6 @@ __attribute__((weak)) void esp_clk_init(void)
 
 #if defined(CONFIG_RTC_CLK_SRC_EXT_CRYS)
     select_rtc_slow_clk(SOC_RTC_SLOW_CLK_SRC_XTAL32K);
-#elif defined(CONFIG_RTC_CLK_SRC_INT_RC32K)
-    select_rtc_slow_clk(SOC_RTC_SLOW_CLK_SRC_RC32K);
 #else
     select_rtc_slow_clk(SOC_RTC_SLOW_CLK_SRC_RC_SLOW);
 #endif
diff --git a/components/soc/esp32c6/include/soc/clk_tree_defs.h b/components/soc/esp32c6/include/soc/clk_tree_defs.h
@@ -24,7 +24,7 @@ extern "C" {
  *    This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
  *    can be computed in runtime through calibration.
  *
- * 4) Internal 32kHz RC Oscillator: RC32K
+ * 4) Internal 32kHz RC Oscillator: RC32K [NOT RECOMMENDED TO USE]
  *
  *    The exact frequency of this clock can be computed in runtime through calibration.
  *
diff --git a/components/soc/esp32h2/include/soc/clk_tree_defs.h b/components/soc/esp32h2/include/soc/clk_tree_defs.h
@@ -24,7 +24,7 @@ extern "C" {
  *    This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
  *    can be computed in runtime through calibration.
  *
- * 4) Internal 32kHz RC Oscillator: RC32K
+ * 4) Internal 32kHz RC Oscillator: RC32K [NOT RECOMMENDED TO USE]
  *
  *    The exact frequency of this clock can be computed in runtime through calibration.
  *
diff --git a/components/soc/esp32p4/include/soc/clk_tree_defs.h b/components/soc/esp32p4/include/soc/clk_tree_defs.h
@@ -26,7 +26,7 @@ extern "C" {
  *    This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
  *    can be computed in runtime through calibration.
  *
- * 4) Internal 32kHz RC Oscillator: RC32K
+ * 4) Internal 32kHz RC Oscillator: RC32K [NOT RECOMMENDED TO USE]
  *
  *    The exact frequency of this clock can be computed in runtime through calibration.
  *
diff --git a/docs/en/api-reference/peripherals/clk_tree.rst b/docs/en/api-reference/peripherals/clk_tree.rst
@@ -79,12 +79,6 @@ Root clocks generate reliable clock signals. These clock signals then pass throu
 
                 A clock signal generated by an external circuit can be connected to {IDF_TARGET_OSC_SLOW_PIN} to be the clock source for the ``RTC_SLOW_CLK``. This clock can also be calibrated to get its exact frequency.
 
-        .. only:: SOC_CLK_RC32K_SUPPORTED
-
-            - Internal 32 kHz RC Oscillator (RC32K)
-
-                The exact frequency of this clock can be computed in runtime through calibration.
-
 Typically, the frequency of the signal generated from an RC oscillator circuit is less accurate and more sensitive to the environment compared to the signal generated from a crystal. {IDF_TARGET_NAME} provides several clock source options for the ``RTC_SLOW_CLK``, and it is possible to make the choice based on the requirements for system time accuracy and power consumption. For more details, please refer to :ref:`rtc-clock-source-choice`.
 
 Module Clocks
diff --git a/docs/en/api-reference/system/system_time.rst b/docs/en/api-reference/system/system_time.rst
@@ -46,8 +46,6 @@ The RTC timer has the following clock sources:
 
     :not esp32c5 and not esp32c6 and not esp32h2 and not esp32p4: - ``Internal {IDF_TARGET_INT_OSC_FRE} oscillator, divided by 256 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``: Provides better frequency stability than the ``Internal {IDF_TARGET_RTC_CLK_FRE} RC oscillator`` at the expense of a higher (by 5 μA) Deep-sleep current consumption. It also does not require external components.
 
-    :esp32c5 or esp32c6 or esp32h2 or esp32p4: - ``Internal 32 kHz RC oscillator``
-
 The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_RTC_CLK_SRC` in project configuration.
 
 More details about the wiring requirements for the external crystal or external oscillator, please refer to the `Hardware Design Guidelines <https://docs.espressif.com/projects/esp-hardware-design-guidelines/en/latest/{IDF_TARGET_PATH_NAME}>`_.
diff --git a/docs/zh_CN/api-reference/peripherals/clk_tree.rst b/docs/zh_CN/api-reference/peripherals/clk_tree.rst
@@ -79,12 +79,6 @@
 
                 将外部电路生成的时钟信号连接到 {IDF_TARGET_OSC_SLOW_PIN}，可作为 ``RTC_SLOW_CLK`` 的时钟源。通过校准，可以计算该时钟信号的实际频率。
 
-        .. only:: SOC_CLK_RC32K_SUPPORTED
-
-            - 内部 32 kHz RC 振荡器 (RC32K)
-
-                在运行时，通过校准，可以计算该时钟信号的实际频率。
-
 与晶振产生的信号相比，从 RC 振荡器电路产生的信号通常精度较低，且容易受环境影响。因此，{IDF_TARGET_NAME} 为 ``RTC_SLOW_CLK`` 提供了几种时钟源选项，可以根据对系统时间精度和对功耗的要求选择。更多详情，请参阅 :ref:`rtc-clock-source-choice`。
 
 模块时钟
diff --git a/docs/zh_CN/api-reference/system/system_time.rst b/docs/zh_CN/api-reference/system/system_time.rst
@@ -46,8 +46,6 @@ RTC 定时器有以下时钟源：
 
     :not esp32c5 and not esp32c6 and not esp32h2 and not esp32p4: - ``内置 {IDF_TARGET_INT_OSC_FRE} 振荡器的 256 分频时钟 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``：频率稳定性优于 ``内置 {IDF_TARGET_RTC_CLK_FRE} RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。
 
-    :esp32c5 or esp32c6 or esp32h2 or esp32p4: - ``内置 32 kHz RC 振荡器``
-
 时钟源的选择取决于系统时间精度要求和睡眠模式下的功耗要求。要修改 RTC 时钟源，请在项目配置中设置 :ref:`CONFIG_RTC_CLK_SRC`。
 
 想要了解外置晶振或外置振荡器的更多布线要求，请参考 `硬件设计指南 <https://docs.espressif.com/projects/esp-hardware-design-guidelines/zh_CN/latest/{IDF_TARGET_PATH_NAME}>`_。

Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ extern "C" {`
`24`	`24`	`* This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock`
`25`	`25`	`* can be computed in runtime through calibration.`
`26`	`26`	`*`
`27`		`- * 4) Internal 32kHz RC Oscillator: RC32K`
	`27`	`+ * 4) Internal 32kHz RC Oscillator: RC32K [NOT RECOMMENDED TO USE]`
`28`	`28`	`*`
`29`	`29`	`* The exact frequency of this clock can be computed in runtime through calibration.`
`30`	`30`	`*`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ extern "C" {`
`26`	`26`	`* This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock`
`27`	`27`	`* can be computed in runtime through calibration.`
`28`	`28`	`*`
`29`		`- * 4) Internal 32kHz RC Oscillator: RC32K`
	`29`	`+ * 4) Internal 32kHz RC Oscillator: RC32K [NOT RECOMMENDED TO USE]`
`30`	`30`	`*`
`31`	`31`	`* The exact frequency of this clock can be computed in runtime through calibration.`
`32`	`32`	`*`