refactor(driver): remove deprecated header files

use esp_private/periph_ctrl.h and esp_private/rtc_cntl.h in favor of
driver/periph_ctrl.h and driver/rtc_cntl.h

components/driver/Kconfig

@@ -1,4 +1,4 @@
-menu "Driver Configurations"
+menu "Legacy Driver Configurations"
 
     orsource "./twai/Kconfig.twai"
 

components/driver/deprecated/driver/periph_ctrl.h

@@ -1,8 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-#pragma once
-#warning driver/periph_ctrl.h header is no longer used, and will be removed in future versions.
-#include "esp_private/periph_ctrl.h"

components/driver/deprecated/driver/rtc_cntl.h

@@ -1,8 +0,0 @@
-/*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-#pragma once
-#warning driver/rtc_cntl.h header is no longer used, and will be removed in future versions.
-#include "esp_private/rtc_ctrl.h"

docs/en/migration-guides/release-6.x/6.0/peripherals.rst

@@ -11,6 +11,16 @@ All drivers' ``io_loop_back`` configuration have been removed
 
 Different driver objects can share the same GPIO number, enabling more complex functionalities. For example, you can bind the TX and RX channels of the RMT peripheral to the same GPIO to simulate 1-Wire bus read and write timing. In previous versions, you needed to configure the ``io_loop_back`` setting in the driver to achieve this "loopback" functionality. Now, this configuration has been removed. Simply configuring the same GPIO number in different drivers will achieve the same functionality.
 
+Peripheral Clock Gating
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Peripheral clock gating is managed within the driver layer. Users do not need to manually handle peripheral module clock gating. Its corresponding APIs are included via a private header file ``esp_private/periph_ctrl.h``. There used to be another header file ``driver/periph_ctrl.h`` for the same purpose, which is now removed.
+
+RTC Subsystem Control
+~~~~~~~~~~~~~~~~~~~~~~
+
+Low power modules usually share some common resources like interrupt number. To avoid conflicts, some private APIs are created in the ``esp_private/rtc_ctrl.h`` header file to manage these shared resources with ease. There used to be another header file ``driver/rtc_cntl.h`` for the same purpose, which is now removed.
+
 ADC
 ---
 

docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst

@@ -11,6 +11,16 @@
 
 不同的驱动对象可以共享同一个 GPIO 编号，联合起来可以实现更加复杂的功能。比如将 RMT 外设的 TX 通道和 RX 通道绑定在同一个 GPIO 上，进而模拟单总线的读写时序。在以前的版本中，你需要在驱动的配置中额外设置 ``io_loop_back`` 来实现这种“回环”功能，现在，这个配置已经被移除。不同的驱动只需要在配置中设置相同的 GPIO 编号就能实现这个功能。
 
+外设时钟门控
+~~~~~~~~~~~~
+
+外设的时钟门控现在由驱动层统一管理，用户无需手动控制外设模块的时钟开关。相关的 API 位于私有头文件 ``esp_private/periph_ctrl.h`` 中。原先用于同样目的的头文件 ``driver/periph_ctrl.h`` 已被移除。
+
+RTC 子系统控制
+~~~~~~~~~~~~~~
+
+低功耗模块通常会共享一些资源，比如中断号。为避免资源冲突，私有头文件 ``esp_private/rtc_ctrl.h`` 提供了相关 API 方便管理这些共享资源。原先用于同样目的的头文件 ``driver/rtc_cntl.h`` 已被移除。
+
 ADC
 ---
 

tools/idf_py_actions/hints.yml

@@ -111,6 +111,12 @@
         -   re_variables: ['driver/can.h']
             hint_variables: ['driver/can.h', 'driver/twai.h']
 
+        -   re_variables: ['driver/periph_ctrl.h']
+            hint_variables: ['driver/periph_ctrl.h', 'esp_private/periph_ctrl.h']
+
+        -   re_variables: ['driver/rtc_cntl.h']
+            hint_variables: ['driver/rtc_cntl.h', 'esp_private/rtc_ctrl.h']
+
 -
     re: "error: implicit declaration of function 'esp_int_wdt_\\w+'"
     hint: 'The Interrupt Watchdog API has been made private, it shall not be used anymore. You can still force its inclusion with #include "esp_private/esp_int_wdt.h" (not recommended)'