From 0296c309088a0825bda4faeac66b8898e93fdd25 Mon Sep 17 00:00:00 2001
From: morris <maoshengrong@espressif.com>
Date: Wed, 4 Dec 2024 13:40:30 +0800
Subject: [PATCH] feat(soc): introduce the soc_caps_full.h for internal use
 only

---
 components/soc/README.md                      | 28 ++++++----
 .../soc/esp32/include/soc/Kconfig.soc_caps.in | 32 +----------
 components/soc/esp32/include/soc/soc_caps.h   | 21 +++----
 .../soc/esp32/include/soc/soc_caps_full.h     | 21 +++++++
 .../esp32c2/include/soc/Kconfig.soc_caps.in   | 20 -------
 components/soc/esp32c2/include/soc/soc_caps.h | 13 ++---
 .../soc/esp32c2/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32c3/include/soc/Kconfig.soc_caps.in   | 24 --------
 components/soc/esp32c3/include/soc/soc_caps.h | 14 ++---
 .../soc/esp32c3/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32c5/include/soc/Kconfig.soc_caps.in   | 24 --------
 components/soc/esp32c5/include/soc/soc_caps.h | 12 ++--
 .../soc/esp32c5/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32c6/include/soc/Kconfig.soc_caps.in   | 24 --------
 components/soc/esp32c6/include/soc/soc_caps.h | 12 ++--
 .../soc/esp32c6/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32c61/include/soc/Kconfig.soc_caps.in  | 24 --------
 .../soc/esp32c61/include/soc/soc_caps.h       | 12 ++--
 .../soc/esp32c61/include/soc/soc_caps_full.h  | 21 +++++++
 .../esp32h2/include/soc/Kconfig.soc_caps.in   | 24 --------
 components/soc/esp32h2/include/soc/soc_caps.h | 12 ++--
 .../soc/esp32h2/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32h21/include/soc/Kconfig.soc_caps.in  | 24 --------
 .../soc/esp32h21/include/soc/soc_caps.h       | 12 ++--
 .../soc/esp32h21/include/soc/soc_caps_full.h  | 21 +++++++
 .../esp32h4/include/soc/Kconfig.soc_caps.in   | 24 --------
 components/soc/esp32h4/include/soc/soc_caps.h | 12 ++--
 .../soc/esp32h4/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32p4/include/soc/Kconfig.soc_caps.in   | 56 -------------------
 components/soc/esp32p4/include/soc/soc_caps.h | 25 +++------
 .../soc/esp32p4/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32s2/include/soc/Kconfig.soc_caps.in   | 24 --------
 components/soc/esp32s2/include/soc/soc_caps.h | 14 ++---
 .../soc/esp32s2/include/soc/soc_caps_full.h   | 21 +++++++
 .../esp32s3/include/soc/Kconfig.soc_caps.in   | 24 --------
 components/soc/esp32s3/include/soc/soc_caps.h | 14 ++---
 .../soc/esp32s3/include/soc/soc_caps_full.h   | 21 +++++++
 components/soc/include/soc/soc_caps_eval.h    | 31 ++++++++++
 components/soc/linux/include/soc/soc_caps.h   |  6 ++
 .../soc/linux/include/soc/soc_caps_full.h     | 10 ++++
 docs/doxygen/Doxyfile                         |  5 +-
 docs/en/api-reference/system/soc_caps.rst     | 30 ++++++++--
 docs/zh_CN/api-reference/system/soc_caps.rst  | 29 ++++++++--
 tools/ci/check_soc_headers_leak.py            | 13 ++---
 .../recommend_way_to_use_soc_caps.yml         | 17 ++++++
 45 files changed, 467 insertions(+), 451 deletions(-)
 create mode 100644 components/soc/esp32/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32c2/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32c3/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32c5/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32c6/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32c61/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32h2/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32h21/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32h4/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32p4/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32s2/include/soc/soc_caps_full.h
 create mode 100644 components/soc/esp32s3/include/soc/soc_caps_full.h
 create mode 100644 components/soc/include/soc/soc_caps_eval.h
 create mode 100644 components/soc/linux/include/soc/soc_caps_full.h
 create mode 100644 tools/ci/sg_rules/recommend_way_to_use_soc_caps.yml

diff --git a/components/soc/README.md b/components/soc/README.md
index c95307a0ec..111ffefc5c 100644
--- a/components/soc/README.md
+++ b/components/soc/README.md
@@ -1,14 +1,22 @@
-## `soc` ##
+# The SoC component
 
-The `soc` component provides hardware description for targets supported by ESP-IDF.
+The `soc` component provides register-level descriptions for targets supported by ESP-IDF.
 
-    - `xxx_reg.h`   - defines registers related to the hardware
-    - `xxx_struct.h` - hardware description in C `struct`
-    - `xxx_channel.h` - definitions for hardware with multiple channels
-    - `xxx_caps.h`  - features/capabilities of the hardware
-    - `xxx_pins.h`  - pin definitions
-    - `xxx_periph.h/*.c`  - includes all headers related to a peripheral; declaration and definition of IO mapping for that hardware
+| File                | Description                                                                                   |
+|---------------------|-----------------------------------------------------------------------------------------------|
+| `xxx_reg.h`/`xx_struct.h` | Defines registers layout of a specific module. These files are automated, and should not be updated manually. <br/> Please note the register names and layout are subject to change between different chip series. |
+| `xxx_pins.h`        | Defines the unchangeable GPIOs used by a specific module. <br/> e.g. if a high speed signal is routed through IO MUX, its corresponding GPIO is not selectable. |
+| `soc_caps.h`        | Describes the differences in capabilities between different chips. <br/> The macros here can also affect cmake build system, Kconfig system, docs system, pytest and CI environment. <br/> **Changes to this file requires extra caution as they are part of the public API.** |
+| `xxx_periph.h`      | This is the portal for each peripheral module at the SoC layer, <br/> containing all relevant register header files and organizing other key information, such as interrupt sources, hardware signal IDs, etc. |
+| `xxx.peripherals.ld` | This is the linker script that defines each module's memory address. |
 
-Specially, the `xxx_reg.h` and `xxx_struct.h` headers that generated by script are under `register/soc` folder. Please DO NOT **add** other manual coded files under this folder.
+## The SoC Capabilities
 
-For other soc headers that are used as wrapper, definition, signaling, mapping or manual coded registers, please add them under `include/soc` folder.
+There are two documents describing SoC capabilities, `soc_caps.h` and `soc_caps_full.h`. The former is a public header file, and the information in it is coarse-grained. The latter is a header file for internal developers that contains fine-grained module information. To used the soc capability macros, you should use the macro functions offered by `soc/soc_caps_eval.h`.
+
+| Macro function | Description | Example |
+|----------------|-------------|---------|
+| `SOC_IS` | Checks if the current SoC is a specific one. | `SOC_IS(ESP32)` |
+| `SOC_HAS` | Checks if the current SoC has a specific module. | `SOC_HAS(DAC)` |
+| `SOC_MODULE_ATTR` | Get the attribute of a specific module. | `SOC_MODULE_ATTR(GPTIMER, TIMERS_TOTAL)` |
+| `SOC_MODULE_SUPPORT` | Checks if the current SoC supports a specific feature. | `SOC_MODULE_SUPPORT(GPTIMER, ETM)` |
diff --git a/components/soc/esp32/include/soc/Kconfig.soc_caps.in b/components/soc/esp32/include/soc/Kconfig.soc_caps.in
index df9a0f1f25..822ad14f2d 100644
--- a/components/soc/esp32/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32/include/soc/Kconfig.soc_caps.in
@@ -191,10 +191,6 @@ config SOC_XTAL_SUPPORT_40M
     bool
     default y
 
-config SOC_XTAL_SUPPORT_AUTO_DETECT
-    bool
-    default y
-
 config SOC_ADC_RTC_CTRL_SUPPORTED
     bool
     default y
@@ -249,11 +245,11 @@ config SOC_ADC_DIGI_MONITOR_NUM
 
 config SOC_ADC_SAMPLE_FREQ_THRES_HIGH
     int
-    default 2
+    default 2000000
 
 config SOC_ADC_SAMPLE_FREQ_THRES_LOW
     int
-    default 20
+    default 20000
 
 config SOC_ADC_RTC_MIN_BITWIDTH
     int
@@ -439,10 +435,6 @@ config SOC_I2S_SUPPORTS_ADC
     bool
     default y
 
-config SOC_I2S_SUPPORTS_DAC
-    bool
-    default y
-
 config SOC_I2S_SUPPORTS_LCD_CAMERA
     bool
     default y
@@ -691,26 +683,6 @@ config SOC_MEMSPI_SRC_FREQ_20M_SUPPORTED
     bool
     default y
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 2
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 64
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 4
-
-config SOC_TIMER_GROUP_SUPPORT_APB
-    bool
-    default y
-
 config SOC_LP_TIMER_BIT_WIDTH_LO
     int
     default 32
diff --git a/components/soc/esp32/include/soc/soc_caps.h b/components/soc/esp32/include/soc/soc_caps.h
index 0cac7c2bf5..9b01e2eb65 100644
--- a/components/soc/esp32/include/soc/soc_caps.h
+++ b/components/soc/esp32/include/soc/soc_caps.h
@@ -37,6 +37,10 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
 #ifdef __has_include
 #  if __has_include("sdkconfig.h")
 #    include "sdkconfig.h"
@@ -55,10 +59,11 @@
 // Define warning strings here for ECO-ed features to show error when they are used without being
 // defined correctly
 #define SOC_BROWNOUT_RESET_SUPPORTED    "Not determined" // [gen_soc_caps:ignore]
-#define SOC_TWAI_BRP_DIV_SUPPORTED      "Not determined" // [gen_soc_caps:ignore]
 #define SOC_DPORT_WORKAROUND            "Not determined" // [gen_soc_caps:ignore]
 #endif
 
+#define _SOC_CAPS_TARGET_IS_ESP32 1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_CAPS_ECO_VER_MAX        301
 
@@ -114,7 +119,6 @@
 /*-------------------------- XTAL CAPS ---------------------------------------*/
 #define SOC_XTAL_SUPPORT_26M            1
 #define SOC_XTAL_SUPPORT_40M            1
-#define SOC_XTAL_SUPPORT_AUTO_DETECT    1   // Measure XTAL freq with an internal RC clock
 
 /*-------------------------- ADC CAPS ----------------------------------------*/
 /*!< SAR ADC Module*/
@@ -135,8 +139,8 @@
 #define SOC_ADC_DIGI_RESULT_BYTES               (2)
 #define SOC_ADC_DIGI_DATA_BYTES_PER_CONV        (4)
 #define SOC_ADC_DIGI_MONITOR_NUM                (0U) // to reference `IDF_TARGET_SOC_ADC_DIGI_MONITOR_NUM` in document
-#define SOC_ADC_SAMPLE_FREQ_THRES_HIGH          (2*1000*1000)
-#define SOC_ADC_SAMPLE_FREQ_THRES_LOW           (20*1000)
+#define SOC_ADC_SAMPLE_FREQ_THRES_HIGH          (2000000)
+#define SOC_ADC_SAMPLE_FREQ_THRES_LOW           (20000)
 
 /*!< RTC */
 #define SOC_ADC_RTC_MIN_BITWIDTH                (9)
@@ -226,7 +230,6 @@
 #define SOC_I2S_PDM_MAX_RX_LINES    (1U)
 #define SOC_I2S_SUPPORTS_ADC_DAC    (1)
 #define SOC_I2S_SUPPORTS_ADC        (1)
-#define SOC_I2S_SUPPORTS_DAC        (1)
 #define SOC_I2S_SUPPORTS_LCD_CAMERA (1)
 #define SOC_I2S_MAX_DATA_WIDTH      (24)
 
@@ -322,13 +325,6 @@
 // Peripheral supports DIO, DOUT, QIO, or QOUT
 #define SOC_SPI_PERIPH_SUPPORT_MULTILINE_MODE(spi_host)         ({(void)spi_host; 1;})
 
-/*-------------------------- TIMER GROUP CAPS --------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (2)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (64)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (4)
-#define SOC_TIMER_GROUP_SUPPORT_APB       (1)
-
 /*-------------------------- LP_TIMER CAPS ----------------------------------*/
 #define SOC_LP_TIMER_BIT_WIDTH_LO           32 // Bit width of lp_timer low part
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
@@ -347,7 +343,6 @@
 #define SOC_TWAI_BRP_MIN                2
 #if SOC_CAPS_ECO_VER >= 200
 #  define SOC_TWAI_BRP_MAX              256
-#  define SOC_TWAI_BRP_DIV_SUPPORTED    1
 #else
 #  define SOC_TWAI_BRP_MAX              128
 #endif
diff --git a/components/soc/esp32/include/soc/soc_caps_full.h b/components/soc/esp32/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..ddee8e204d
--- /dev/null
+++ b/components/soc/esp32/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       64 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         2  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32c2/include/soc/Kconfig.soc_caps.in b/components/soc/esp32c2/include/soc/Kconfig.soc_caps.in
index ab19f7ca6a..d0d74a5292 100644
--- a/components/soc/esp32c2/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32c2/include/soc/Kconfig.soc_caps.in
@@ -603,26 +603,6 @@ config SOC_SYSTIMER_ALARM_MISS_COMPENSATE
     bool
     default y
 
-config SOC_TIMER_GROUPS
-    int
-    default 1
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 1
-
 config SOC_LP_TIMER_BIT_WIDTH_LO
     int
     default 32
diff --git a/components/soc/esp32c2/include/soc/soc_caps.h b/components/soc/esp32c2/include/soc/soc_caps.h
index 89189ee996..facf692980 100644
--- a/components/soc/esp32c2/include/soc/soc_caps.h
+++ b/components/soc/esp32c2/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32C2     1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_DEDICATED_GPIO_SUPPORTED    1
@@ -268,13 +274,6 @@
 #define SOC_SYSTIMER_INT_LEVEL              1  // Systimer peripheral uses level interrupt
 #define SOC_SYSTIMER_ALARM_MISS_COMPENSATE  1  // Systimer peripheral can generate interrupt immediately if t(target) > t(current)
 
-/*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (1U)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (1U)
-
 /*-------------------------- LP_TIMER CAPS ----------------------------------*/
 #define SOC_LP_TIMER_BIT_WIDTH_LO           32 // Bit width of lp_timer low part
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
diff --git a/components/soc/esp32c2/include/soc/soc_caps_full.h b/components/soc/esp32c2/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..3d94d0e63b
--- /dev/null
+++ b/components/soc/esp32c2/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   1 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32c3/include/soc/Kconfig.soc_caps.in b/components/soc/esp32c3/include/soc/Kconfig.soc_caps.in
index afaa031a1c..1d5fbd4d16 100644
--- a/components/soc/esp32c3/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32c3/include/soc/Kconfig.soc_caps.in
@@ -863,30 +863,6 @@ config SOC_SYSTIMER_ALARM_MISS_COMPENSATE
     bool
     default y
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_APB
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 2
-
 config SOC_LP_TIMER_BIT_WIDTH_LO
     int
     default 32
diff --git a/components/soc/esp32c3/include/soc/soc_caps.h b/components/soc/esp32c3/include/soc/soc_caps.h
index 9c0b52212c..5f56f39f7c 100644
--- a/components/soc/esp32c3/include/soc/soc_caps.h
+++ b/components/soc/esp32c3/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32C3     1  // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_DEDICATED_GPIO_SUPPORTED    1
@@ -363,14 +369,6 @@
 #define SOC_SYSTIMER_INT_LEVEL              1  // Systimer peripheral uses level interrupt
 #define SOC_SYSTIMER_ALARM_MISS_COMPENSATE  1  // Systimer peripheral can generate interrupt immediately if t(target) > t(current)
 
-/*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_APB       (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (2)
-
 /*-------------------------- LP_TIMER CAPS ----------------------------------*/
 #define SOC_LP_TIMER_BIT_WIDTH_LO           32 // Bit width of lp_timer low part
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
diff --git a/components/soc/esp32c3/include/soc/soc_caps_full.h b/components/soc/esp32c3/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..6ccb00bd76
--- /dev/null
+++ b/components/soc/esp32c3/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32c5/include/soc/Kconfig.soc_caps.in b/components/soc/esp32c5/include/soc/Kconfig.soc_caps.in
index 8e75e2282b..74cad114a6 100644
--- a/components/soc/esp32c5/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32c5/include/soc/Kconfig.soc_caps.in
@@ -1303,30 +1303,6 @@ config SOC_LP_TIMER_BIT_WIDTH_HI
     int
     default 16
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_RC_FAST
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 2
-
 config SOC_TIMER_SUPPORT_ETM
     bool
     default y
diff --git a/components/soc/esp32c5/include/soc/soc_caps.h b/components/soc/esp32c5/include/soc/soc_caps.h
index 1236a27002..1462f78521 100644
--- a/components/soc/esp32c5/include/soc/soc_caps.h
+++ b/components/soc/esp32c5/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32C5     1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_ANA_CMPR_SUPPORTED          1
@@ -505,12 +511,6 @@
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
 
 /*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_RC_FAST   (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (2)
 #define SOC_TIMER_SUPPORT_ETM             (1)
 #define SOC_TIMER_SUPPORT_SLEEP_RETENTION (1)
 
diff --git a/components/soc/esp32c5/include/soc/soc_caps_full.h b/components/soc/esp32c5/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..6ccb00bd76
--- /dev/null
+++ b/components/soc/esp32c5/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in b/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in
index 5ce5ce225a..399e48e196 100644
--- a/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in
@@ -1163,30 +1163,6 @@ config SOC_LP_TIMER_BIT_WIDTH_HI
     int
     default 16
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_RC_FAST
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 2
-
 config SOC_TIMER_SUPPORT_ETM
     bool
     default y
diff --git a/components/soc/esp32c6/include/soc/soc_caps.h b/components/soc/esp32c6/include/soc/soc_caps.h
index 69ee2751bb..38218f04f4 100644
--- a/components/soc/esp32c6/include/soc/soc_caps.h
+++ b/components/soc/esp32c6/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32C6     1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_DEDICATED_GPIO_SUPPORTED    1
@@ -454,12 +460,6 @@
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
 
 /*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_RC_FAST   (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (2)
 #define SOC_TIMER_SUPPORT_ETM             (1)
 #define SOC_TIMER_SUPPORT_SLEEP_RETENTION (1)
 
diff --git a/components/soc/esp32c6/include/soc/soc_caps_full.h b/components/soc/esp32c6/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..6ccb00bd76
--- /dev/null
+++ b/components/soc/esp32c6/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32c61/include/soc/Kconfig.soc_caps.in b/components/soc/esp32c61/include/soc/Kconfig.soc_caps.in
index 736d270577..c00c0a0e08 100644
--- a/components/soc/esp32c61/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32c61/include/soc/Kconfig.soc_caps.in
@@ -891,30 +891,6 @@ config SOC_LP_TIMER_BIT_WIDTH_HI
     int
     default 16
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_RC_FAST
-    bool
-    default y
-
 config SOC_TIMER_SUPPORT_SLEEP_RETENTION
     bool
     default y
diff --git a/components/soc/esp32c61/include/soc/soc_caps.h b/components/soc/esp32c61/include/soc/soc_caps.h
index b78fc7efd1..b080b1b16b 100644
--- a/components/soc/esp32c61/include/soc/soc_caps.h
+++ b/components/soc/esp32c61/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32C61    1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_ANA_CMPR_SUPPORTED          1
@@ -369,12 +375,6 @@
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
 
 /*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (2)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_RC_FAST   (1)
 #define SOC_TIMER_SUPPORT_SLEEP_RETENTION (1)
 #define SOC_TIMER_SUPPORT_ETM             (1)
 
diff --git a/components/soc/esp32c61/include/soc/soc_caps_full.h b/components/soc/esp32c61/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..6ccb00bd76
--- /dev/null
+++ b/components/soc/esp32c61/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32h2/include/soc/Kconfig.soc_caps.in b/components/soc/esp32h2/include/soc/Kconfig.soc_caps.in
index 8386f8164c..5519a4f074 100644
--- a/components/soc/esp32h2/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32h2/include/soc/Kconfig.soc_caps.in
@@ -1179,30 +1179,6 @@ config SOC_LP_TIMER_BIT_WIDTH_HI
     int
     default 16
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_RC_FAST
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 2
-
 config SOC_TIMER_SUPPORT_ETM
     bool
     default y
diff --git a/components/soc/esp32h2/include/soc/soc_caps.h b/components/soc/esp32h2/include/soc/soc_caps.h
index d1762192fa..987072daa6 100644
--- a/components/soc/esp32h2/include/soc/soc_caps.h
+++ b/components/soc/esp32h2/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32H2 1 // [gen_soc_caps:ignore]
+
 #ifdef __has_include
 #  if __has_include("sdkconfig.h")
 #    include "sdkconfig.h"
@@ -472,12 +478,6 @@
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
 
 /*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_RC_FAST   (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (2)
 #define SOC_TIMER_SUPPORT_ETM             (1)
 #define SOC_TIMER_SUPPORT_SLEEP_RETENTION (1)
 
diff --git a/components/soc/esp32h2/include/soc/soc_caps_full.h b/components/soc/esp32h2/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..6ccb00bd76
--- /dev/null
+++ b/components/soc/esp32h2/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32h21/include/soc/Kconfig.soc_caps.in b/components/soc/esp32h21/include/soc/Kconfig.soc_caps.in
index 2eb7f5658b..4d7459a3d0 100644
--- a/components/soc/esp32h21/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32h21/include/soc/Kconfig.soc_caps.in
@@ -639,30 +639,6 @@ config SOC_LP_TIMER_BIT_WIDTH_HI
     int
     default 16
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_RC_FAST
-    bool
-    default y
-
 config SOC_TIMER_SUPPORT_SLEEP_RETENTION
     bool
     default y
diff --git a/components/soc/esp32h21/include/soc/soc_caps.h b/components/soc/esp32h21/include/soc/soc_caps.h
index f24a27ff26..4c3ee38c25 100644
--- a/components/soc/esp32h21/include/soc/soc_caps.h
+++ b/components/soc/esp32h21/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32H21  1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 // #define SOC_ADC_SUPPORTED               1    //TODO: [ESP32H21] IDF-11589, IDF-11592
 // #define SOC_ANA_CMPR_SUPPORTED          1
@@ -436,12 +442,6 @@
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
 
 /*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (2)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_RC_FAST   (1)
 // #define SOC_TIMER_SUPPORT_ETM             (1)    //TODO: [ESP32H21] IDF-11576
 #define SOC_TIMER_SUPPORT_SLEEP_RETENTION (1)
 
diff --git a/components/soc/esp32h21/include/soc/soc_caps_full.h b/components/soc/esp32h21/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..6ccb00bd76
--- /dev/null
+++ b/components/soc/esp32h21/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32h4/include/soc/Kconfig.soc_caps.in b/components/soc/esp32h4/include/soc/Kconfig.soc_caps.in
index 6a35968adc..c550a04cff 100644
--- a/components/soc/esp32h4/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32h4/include/soc/Kconfig.soc_caps.in
@@ -399,30 +399,6 @@ config SOC_LP_TIMER_BIT_WIDTH_HI
     int
     default 16
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 1
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_RC_FAST
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 2
-
 config SOC_TIMER_SUPPORT_SLEEP_RETENTION
     bool
     default y
diff --git a/components/soc/esp32h4/include/soc/soc_caps.h b/components/soc/esp32h4/include/soc/soc_caps.h
index 95d49a0e18..efc5dd5fdc 100644
--- a/components/soc/esp32h4/include/soc/soc_caps.h
+++ b/components/soc/esp32h4/include/soc/soc_caps.h
@@ -24,6 +24,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32H4        1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 // #define SOC_ADC_SUPPORTED               1    // TODO: [ESP32H4] IDF-12368 IDF-12370
 // #define SOC_ANA_CMPR_SUPPORTED          1    // TODO: [ESP32H4] IDF-12395 big change!!
@@ -428,12 +434,6 @@
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
 
 /*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (1U)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_RC_FAST   (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (2)
 // #define SOC_TIMER_SUPPORT_ETM             (1)     // TODO: [ESP32H4] IDF-12355
 #define SOC_TIMER_SUPPORT_SLEEP_RETENTION (1)
 
diff --git a/components/soc/esp32h4/include/soc/soc_caps_full.h b/components/soc/esp32h4/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..6ccb00bd76
--- /dev/null
+++ b/components/soc/esp32h4/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         1  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32p4/include/soc/Kconfig.soc_caps.in b/components/soc/esp32p4/include/soc/Kconfig.soc_caps.in
index 6434548167..af6be8588c 100644
--- a/components/soc/esp32p4/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32p4/include/soc/Kconfig.soc_caps.in
@@ -1563,10 +1563,6 @@ config SOC_SPI_SUPPORT_CLK_RC_FAST
     bool
     default y
 
-config SOC_SPI_SUPPORT_CLK_SPLL
-    bool
-    default y
-
 config SOC_MSPI_HAS_INDEPENT_IOMUX
     bool
     default y
@@ -1579,10 +1575,6 @@ config SOC_SPI_MAX_PRE_DIVIDER
     int
     default 16
 
-config SOC_LP_SPI_PERIPH_NUM
-    bool
-    default y
-
 config SOC_LP_SPI_MAXIMUM_BUFFER_SIZE
     int
     default 64
@@ -1651,10 +1643,6 @@ config SOC_MEMSPI_SRC_FREQ_120M_SUPPORTED
     bool
     default y
 
-config SOC_MEMSPI_FLASH_PSRAM_INDEPENDENT
-    bool
-    default y
-
 config SOC_SYSTIMER_COUNTER_NUM
     int
     default 2
@@ -1699,30 +1687,6 @@ config SOC_LP_TIMER_BIT_WIDTH_HI
     int
     default 16
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 2
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_RC_FAST
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 4
-
 config SOC_TIMER_SUPPORT_ETM
     bool
     default y
@@ -2075,10 +2039,6 @@ config SOC_PM_RETENTION_MODULE_NUM
     int
     default 64
 
-config SOC_PSRAM_VDD_POWER_MPLL
-    bool
-    default y
-
 config SOC_CLK_RC_FAST_SUPPORT_CALIBRATION
     bool
     default y
@@ -2115,10 +2075,6 @@ config SOC_PERIPH_CLK_CTRL_SHARED
     bool
     default y
 
-config SOC_TEMPERATURE_SENSOR_LP_PLL_SUPPORT
-    bool
-    default y
-
 config SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
     bool
     default y
@@ -2183,14 +2139,6 @@ config SOC_I3C_MASTER_PERIPH_NUM
     bool
     default y
 
-config SOC_I3C_MASTER_ADDRESS_TABLE_NUM
-    int
-    default 12
-
-config SOC_I3C_MASTER_COMMAND_TABLE_NUM
-    int
-    default 12
-
 config SOC_LP_CORE_SUPPORT_ETM
     bool
     default y
@@ -2199,10 +2147,6 @@ config SOC_LP_CORE_SUPPORT_LP_ADC
     bool
     default y
 
-config SOC_LP_CORE_SUPPORT_LP_VAD
-    bool
-    default y
-
 config SOC_LP_CORE_SUPPORT_STORE_LOAD_EXCEPTIONS
     bool
     default y
diff --git a/components/soc/esp32p4/include/soc/soc_caps.h b/components/soc/esp32p4/include/soc/soc_caps.h
index 3437a77b53..4f9a7dc984 100644
--- a/components/soc/esp32p4/include/soc/soc_caps.h
+++ b/components/soc/esp32p4/include/soc/soc_caps.h
@@ -16,6 +16,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32P4     1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_ANA_CMPR_SUPPORTED          1
@@ -227,7 +233,6 @@
 #define SOC_DMA2D_GROUPS                            (1U) // Number of 2D-DMA groups
 #define SOC_DMA2D_TX_CHANNELS_PER_GROUP             (3)  // Number of 2D-DMA TX (OUT) channels in each group
 #define SOC_DMA2D_RX_CHANNELS_PER_GROUP             (2)  // Number of 2D-DMA RX (IN) channels in each group
-// #define SOC_DMA2D_SUPPORT_ETM              (1)  // Support ETM submodule
 
 /*-------------------------- ETM CAPS --------------------------------------*/
 #define SOC_ETM_GROUPS                  1U  // Number of ETM groups
@@ -571,7 +576,6 @@
 #define SOC_SPI_SUPPORT_OCT                 1
 #define SOC_SPI_SUPPORT_CLK_XTAL            1
 #define SOC_SPI_SUPPORT_CLK_RC_FAST         1
-#define SOC_SPI_SUPPORT_CLK_SPLL            1
 
 // Peripheral supports DIO, DOUT, QIO, or QOUT
 // host_id = 0 -> SPI0/SPI1, host_id = 1 -> SPI2,
@@ -582,8 +586,8 @@
 #define SOC_SPI_MAX_PRE_DIVIDER     16
 
 /*-------------------------- LP SPI CAPS ----------------------------------------*/
-#define SOC_LP_SPI_PERIPH_NUM              1
 #define SOC_LP_SPI_MAXIMUM_BUFFER_SIZE     64
+
 /*-------------------------- SPIRAM CAPS ----------------------------------------*/
 #define SOC_SPIRAM_XIP_SUPPORTED        1
 
@@ -607,8 +611,6 @@
 #define SOC_MEMSPI_SRC_FREQ_20M_SUPPORTED         1
 #define SOC_MEMSPI_SRC_FREQ_120M_SUPPORTED        1
 
-#define SOC_MEMSPI_FLASH_PSRAM_INDEPENDENT        1
-
 /*-------------------------- SYSTIMER CAPS ----------------------------------*/
 #define SOC_SYSTIMER_COUNTER_NUM            2  // Number of counter units
 #define SOC_SYSTIMER_ALARM_NUM              3  // Number of alarm units
@@ -625,12 +627,6 @@
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
 
 /*--------------------------- TIMER GROUP CAPS ---------------------------------------*/
-#define SOC_TIMER_GROUPS                  2
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  2
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH 54
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      1
-#define SOC_TIMER_GROUP_SUPPORT_RC_FAST   1
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      4
 #define SOC_TIMER_SUPPORT_ETM             1
 #define SOC_TIMER_SUPPORT_SLEEP_RETENTION 1
 
@@ -764,9 +760,6 @@
 
 #define SOC_PM_RETENTION_MODULE_NUM         (64)
 
-/*-------------------------- PSRAM CAPS ----------------------------*/
-#define SOC_PSRAM_VDD_POWER_MPLL    (1)
-
 /*-------------------------- CLOCK SUBSYSTEM CAPS ----------------------------------------*/
 #define SOC_CLK_RC_FAST_SUPPORT_CALIBRATION       (1)
 
@@ -782,7 +775,6 @@
 #define SOC_PERIPH_CLK_CTRL_SHARED                (1)     /*!< Peripheral clock control (e.g. set clock source) is shared between various peripherals */
 
 /*-------------------------- Temperature Sensor CAPS -------------------------------------*/
-#define SOC_TEMPERATURE_SENSOR_LP_PLL_SUPPORT                (1)
 #define SOC_TEMPERATURE_SENSOR_INTR_SUPPORT                  (1)
 #define SOC_TSENS_IS_INDEPENDENT_FROM_ADC                    (1)  /*!< Temperature sensor is a separate module, not share regs with ADC */
 #define SOC_TEMPERATURE_SENSOR_SUPPORT_ETM                   (1)
@@ -809,11 +801,8 @@
 
 /*--------------------------- I3C ---------------------------------*/
 #define SOC_I3C_MASTER_PERIPH_NUM                   (1)
-#define SOC_I3C_MASTER_ADDRESS_TABLE_NUM            (12)
-#define SOC_I3C_MASTER_COMMAND_TABLE_NUM            (12)
 
 /*------------------------------------- ULP CAPS -------------------------------------*/
 #define SOC_LP_CORE_SUPPORT_ETM                     (1) /*!< LP Core supports ETM */
 #define SOC_LP_CORE_SUPPORT_LP_ADC                  (1) /*!< LP ADC can be accessed from the LP-Core */
-#define SOC_LP_CORE_SUPPORT_LP_VAD                  (1) /*!< LP VAD can be accessed from the LP-Core */
 #define SOC_LP_CORE_SUPPORT_STORE_LOAD_EXCEPTIONS   (1) /*!< LP Core will raise exceptions if accessing invalid addresses */
diff --git a/components/soc/esp32p4/include/soc/soc_caps_full.h b/components/soc/esp32p4/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..c444468053
--- /dev/null
+++ b/components/soc/esp32p4/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         2  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32s2/include/soc/Kconfig.soc_caps.in b/components/soc/esp32s2/include/soc/Kconfig.soc_caps.in
index 58e4996e97..fdf69ab06d 100644
--- a/components/soc/esp32s2/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32s2/include/soc/Kconfig.soc_caps.in
@@ -791,30 +791,6 @@ config SOC_SYSTIMER_BIT_WIDTH_HI
     int
     default 32
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 2
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 64
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_APB
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 4
-
 config SOC_LP_TIMER_BIT_WIDTH_LO
     int
     default 32
diff --git a/components/soc/esp32s2/include/soc/soc_caps.h b/components/soc/esp32s2/include/soc/soc_caps.h
index edb1119c19..8ccc41b362 100644
--- a/components/soc/esp32s2/include/soc/soc_caps.h
+++ b/components/soc/esp32s2/include/soc/soc_caps.h
@@ -36,6 +36,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32S2     1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_DAC_SUPPORTED               1
@@ -334,14 +340,6 @@
 #define SOC_SYSTIMER_BIT_WIDTH_LO 32 // Bit width of systimer low part
 #define SOC_SYSTIMER_BIT_WIDTH_HI 32 // Bit width of systimer high part
 
-/*-------------------------- TIMER GROUP CAPS --------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (2)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (64)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_APB       (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (4)
-
 /*-------------------------- LP_TIMER CAPS ----------------------------------*/
 #define SOC_LP_TIMER_BIT_WIDTH_LO           32 // Bit width of lp_timer low part
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
diff --git a/components/soc/esp32s2/include/soc/soc_caps_full.h b/components/soc/esp32s2/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..ddee8e204d
--- /dev/null
+++ b/components/soc/esp32s2/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       64 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         2  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/esp32s3/include/soc/Kconfig.soc_caps.in b/components/soc/esp32s3/include/soc/Kconfig.soc_caps.in
index aa81895665..735104e4ff 100644
--- a/components/soc/esp32s3/include/soc/Kconfig.soc_caps.in
+++ b/components/soc/esp32s3/include/soc/Kconfig.soc_caps.in
@@ -995,30 +995,6 @@ config SOC_SYSTIMER_ALARM_MISS_COMPENSATE
     bool
     default y
 
-config SOC_TIMER_GROUPS
-    int
-    default 2
-
-config SOC_TIMER_GROUP_TIMERS_PER_GROUP
-    int
-    default 2
-
-config SOC_TIMER_GROUP_COUNTER_BIT_WIDTH
-    int
-    default 54
-
-config SOC_TIMER_GROUP_SUPPORT_XTAL
-    bool
-    default y
-
-config SOC_TIMER_GROUP_SUPPORT_APB
-    bool
-    default y
-
-config SOC_TIMER_GROUP_TOTAL_TIMERS
-    int
-    default 4
-
 config SOC_LP_TIMER_BIT_WIDTH_LO
     int
     default 32
diff --git a/components/soc/esp32s3/include/soc/soc_caps.h b/components/soc/esp32s3/include/soc/soc_caps.h
index 28ad1055ee..b455d19e3f 100644
--- a/components/soc/esp32s3/include/soc/soc_caps.h
+++ b/components/soc/esp32s3/include/soc/soc_caps.h
@@ -21,6 +21,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_ESP32S3     1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_ADC_SUPPORTED               1
 #define SOC_UART_SUPPORTED              1
@@ -386,14 +392,6 @@
 #define SOC_SYSTIMER_INT_LEVEL              1  // Systimer peripheral uses level
 #define SOC_SYSTIMER_ALARM_MISS_COMPENSATE  1  // Systimer peripheral can generate interrupt immediately if t(target) > t(current)
 
-/*-------------------------- TIMER GROUP CAPS --------------------------------*/
-#define SOC_TIMER_GROUPS                  (2)
-#define SOC_TIMER_GROUP_TIMERS_PER_GROUP  (2)
-#define SOC_TIMER_GROUP_COUNTER_BIT_WIDTH (54)
-#define SOC_TIMER_GROUP_SUPPORT_XTAL      (1)
-#define SOC_TIMER_GROUP_SUPPORT_APB       (1)
-#define SOC_TIMER_GROUP_TOTAL_TIMERS      (4)
-
 /*-------------------------- LP_TIMER CAPS ----------------------------------*/
 #define SOC_LP_TIMER_BIT_WIDTH_LO           32 // Bit width of lp_timer low part
 #define SOC_LP_TIMER_BIT_WIDTH_HI           16 // Bit width of lp_timer high part
diff --git a/components/soc/esp32s3/include/soc/soc_caps_full.h b/components/soc/esp32s3/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..c444468053
--- /dev/null
+++ b/components/soc/esp32s3/include/soc/soc_caps_full.h
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
+
+/*--------------------------- Timer Group -------------------------------------------*/
+#define _SOC_CAPS_TIMG_INST_NUM                   2 // Number of Timer Group instances
+
+/*--------------------------- GPTIMER ---------------------------------------*/
+#define _SOC_CAPS_GPTIMER_COUNTER_BIT_WIDTH       54 // Bit width of GPTIMER counter
+#define _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG         2  // Number of general purpose timers in each Timer Group
+#define _SOC_CAPS_GPTIMER_TIMERS_TOTAL            (_SOC_CAPS_TIMG_INST_NUM * _SOC_CAPS_GPTIMER_TIMERS_PER_TIMG)
+
+/*--------------------------- Watch Dog ------------------------------------------*/
+#define _SOC_CAPS_WDT_MWDTS_PER_TIMG              1  // Number of main watchdog timers in each Timer Group
diff --git a/components/soc/include/soc/soc_caps_eval.h b/components/soc/include/soc/soc_caps_eval.h
new file mode 100644
index 0000000000..b078dcc94c
--- /dev/null
+++ b/components/soc/include/soc/soc_caps_eval.h
@@ -0,0 +1,31 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+/**
+ * SOC Capability evaluation helpers
+ *
+ * These macros provide a standardized way to query SOC capabilities without directly
+ * accessing internal implementation macros in soc_caps_full.h and public macros in soc_caps.h.
+ *
+ * The main categories of macros are:
+ * - SOC_IS : Check if the SOC is a specific target (e.g., SOC_IS(ESP32S3))
+ * - SOC_MODULE_ATTR : Get a specific attribute of a module (e.g., SOC_MODULE_ATTR(GPTIMER, NUM))
+ * - SOC_MODULE_SUPPORT : Check if a module supports a feature (e.g., SOC_MODULE_SUPPORT(GPTIMER, ETM))
+ */
+
+#define _SOC_CAPS_EVAL(_name)               _SOC_CAPS_ ## _name
+
+/* User-facing semantic macros */
+// Check if the SOC has a specific module
+#define SOC_HAS(_module)                    SOC_ ## _module ## _SUPPORTED
+// Check if the SOC is a specific target
+#define SOC_IS(_target)                     _SOC_CAPS_EVAL(TARGET_IS_ ## _target)
+// Generic query macro, which can be used to get any module attribute (e.g. version, ID, number, etc.)
+#define SOC_MODULE_ATTR(_module, _attr)     _SOC_CAPS_EVAL(_module ## _ ## _attr)
+// Generic support check macro, which can be used to check if a module supports a specific feature (e.g. ETM, DMA, etc.)
+#define SOC_MODULE_SUPPORT(_module, _feat)  _SOC_CAPS_EVAL(_module ## _SUPPORT_ ## _feat)
diff --git a/components/soc/linux/include/soc/soc_caps.h b/components/soc/linux/include/soc/soc_caps.h
index 73f1a552d5..1b9d13da22 100644
--- a/components/soc/linux/include/soc/soc_caps.h
+++ b/components/soc/linux/include/soc/soc_caps.h
@@ -21,6 +21,12 @@
 
 #pragma once
 
+#if __has_include("soc/soc_caps_eval.h")
+#include "soc/soc_caps_eval.h"
+#endif
+
+#define _SOC_CAPS_TARGET_IS_HOST 1 // [gen_soc_caps:ignore]
+
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_EFUSE_SUPPORTED                 (1)
 #define SOC_EFUSE_KEY_PURPOSE_FIELD         (1)
diff --git a/components/soc/linux/include/soc/soc_caps_full.h b/components/soc/linux/include/soc/soc_caps_full.h
new file mode 100644
index 0000000000..ca1d6414d9
--- /dev/null
+++ b/components/soc/linux/include/soc/soc_caps_full.h
@@ -0,0 +1,10 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "soc/soc_caps_eval.h"
diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile
index fd8edf3afe..fcfd4d363c 100644
--- a/docs/doxygen/Doxyfile
+++ b/docs/doxygen/Doxyfile
@@ -16,7 +16,7 @@
 PROJECT_NAME = "IDF Programming Guide"
 
 ## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
-## to automatically generate API reference list files heder_file.inc
+## to automatically generate API reference list files header_file.inc
 ## These files are placed in '_inc' directory
 ## and used to include in API reference documentation
 
@@ -311,7 +311,8 @@ INPUT = \
     $(PROJECT_PATH)/components/protocomm/include/crypto/srp6a/esp_srp.h \
     $(PROJECT_PATH)/components/pthread/include/esp_pthread.h \
     $(PROJECT_PATH)/components/sdmmc/include/sdmmc_cmd.h \
-	$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/adc_channel.h \
+    $(PROJECT_PATH)/components/soc/include/soc/soc_caps_eval.h \
+    $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/adc_channel.h \
     $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/clk_tree_defs.h \
     $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/gpio_num.h \
     $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/soc_caps.h \
diff --git a/docs/en/api-reference/system/soc_caps.rst b/docs/en/api-reference/system/soc_caps.rst
index 74ab7c9475..2777a25f03 100644
--- a/docs/en/api-reference/system/soc_caps.rst
+++ b/docs/en/api-reference/system/soc_caps.rst
@@ -1,16 +1,36 @@
-SoC Capabilities
-================
+SoC Capability Macros
+=====================
 
 :link_to_translation:`zh_CN:[中文]`
 
-This section lists the macro definitions of the {IDF_TARGET_NAME}'s SoC hardware capabilities. These macros are commonly used by conditional-compilation directives (e.g., ``#if``) in ESP-IDF to determine which hardware-dependent features are supported, thus control what portions of code are compiled.
+Different models of ESP chips integrate various hardware modules. Even the same type of module may have subtle differences across different chips. ESP-IDF provides a small "database" to describe the differences between chips (please note, only differences are described, not commonalities). The contents of this "database" are defined as macros in the **soc/soc_caps.h** file, referred to as **SoC capability macros**. Users can utilize these macros in their code with conditional compilation directives (such as ``#if``) to control which code is actually compiled.
 
-.. warning::
+.. note::
 
-    These macro definitions are currently not considered to be part of the public API, and may be changed in a breaking manner (see :doc:`../../../versions` for more details).
+    Please note that the contents of **soc/soc_caps.h** are currently unstable and may undergo significant changes in the future.
+
+Using SoC Capability Macros
+---------------------------
+
+We recommend accessing SoC capability macros indirectly through the following macro functions:
+
+.. list-table::
+    :widths: 30 60 80
+    :header-rows: 1
+
+    * - Macro Function
+      - Description
+      - Example
+    * - :c:macro:`SOC_IS`
+      - Determines the chip model
+      - ``#if SOC_IS(ESP32)`` checks if the chip is ESP32
+    * - :c:macro:`SOC_HAS`
+      - Checks if the chip has a specific hardware module or feature
+      - ``#if SOC_HAS(DAC)`` checks if the chip has a DAC module
 
 
 API Reference
 -------------
 
 .. include-build-file:: inc/soc_caps.inc
+.. include-build-file:: inc/soc_caps_eval.inc
diff --git a/docs/zh_CN/api-reference/system/soc_caps.rst b/docs/zh_CN/api-reference/system/soc_caps.rst
index 5321eb7b4e..7f44415720 100644
--- a/docs/zh_CN/api-reference/system/soc_caps.rst
+++ b/docs/zh_CN/api-reference/system/soc_caps.rst
@@ -1,16 +1,35 @@
-SoC 功能
-================
+SoC 能力宏
+==========
 
 :link_to_translation:`en:[English]`
 
-此文档介绍了 {IDF_TARGET_NAME} SoC 硬件功能的宏定义。ESP-IDF 中的条件编译指令通常使用这些宏来确定哪些依赖于硬件的功能受到支持，从而控制需编译的代码内容。
+不同型号的 ESP 芯片内部会集成不同的硬件模块。哪怕是同一种模块，在不同的芯片上也可能具有细微的差异。ESP-IDF 中提供了一份小型的“数据库”来描述不同芯片之间的差异（注意，我们不描述共性，只描述差异）。这份“数据库“的内容以宏定义的形式定义在 **soc/soc_caps.h** 文件中，我们称之为 **SoC 能力宏**。用户可以通过在代码中使用条件编译指令（比如 ``#if``）来使用这些宏，从而控制实际需要编译的代码内容。
 
 .. note::
 
-    目前，这些宏定义不属于公共 API，未来可能发生重大更改。如需了解详情，请前往 :doc:`../../../versions`。
+    请注意， **soc/soc_caps.h** 中的内容目前还不稳定，未来可能会发生重大更改。
 
+使用 SoC 能力宏
+---------------
+
+我们推荐通过下面的宏函数来间接地访问 SoC 能力宏：
+
+.. list-table::
+    :widths: 30 60 80
+    :header-rows: 1
+
+    * - 宏函数
+      - 描述
+      - 示例
+    * - :c:macro:`SOC_IS`
+      - 判断芯片型号
+      - ``#if SOC_IS(ESP32)`` 判断是否为 ESP32 芯片
+    * - :c:macro:`SOC_HAS`
+      - 判断芯片是否具有某个硬件模块或功能
+      - ``#if SOC_HAS(DAC)`` 判断是否具有 DAC 模块
 
 API 参考
--------------
+--------
 
 .. include-build-file:: inc/soc_caps.inc
+.. include-build-file:: inc/soc_caps_eval.inc
diff --git a/tools/ci/check_soc_headers_leak.py b/tools/ci/check_soc_headers_leak.py
index 7e447d17dd..62a58c72a9 100755
--- a/tools/ci/check_soc_headers_leak.py
+++ b/tools/ci/check_soc_headers_leak.py
@@ -13,6 +13,7 @@ from string import Template
 # The following header files in soc component is treated as stable, so is allowed to be used in any public header files
 allowed_soc_headers = (
     'soc/soc_caps.h',
+    'soc/soc_caps_eval.h',
     'soc/gpio_num.h',
     'soc/reset_reasons.h',
     'soc/reg_base.h',
@@ -39,9 +40,7 @@ class PublicAPIVisits:
                     # $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/uart_channel.h \
                     # -> ${PROJECT_PATH}/components/soc/${IDF_TARGET}/include/soc/uart_channel.h
                     line = line.replace('(', '{').replace(')', '}').rstrip('\\ ')
-                    file_path = Template(line).substitute(
-                        PROJECT_PATH=self._idf_path, IDF_TARGET=self._target
-                    )
+                    file_path = Template(line).substitute(PROJECT_PATH=self._idf_path, IDF_TARGET=self._target)
                     yield file_path
 
 
@@ -51,9 +50,7 @@ def check_soc_not_in(
     doxyfile_path: str,
     violation_dict: typing.Dict[str, set],
 ) -> None:
-    for file_path in PublicAPIVisits(
-        os.path.join(idf_path, doxyfile_path), idf_path, target
-    ):
+    for file_path in PublicAPIVisits(os.path.join(idf_path, doxyfile_path), idf_path, target):
         with open(file_path, 'r', encoding='utf8') as f:
             for line in f:
                 match_data = re.match(include_header_pattern, line)
@@ -72,9 +69,7 @@ def main() -> None:
         sys.exit(1)
 
     # list all doxyfiles
-    doxyfiles = fnmatch.filter(
-        os.listdir(os.path.join(idf_path, 'docs/doxygen')), 'Doxyfile*'
-    )
+    doxyfiles = fnmatch.filter(os.listdir(os.path.join(idf_path, 'docs/doxygen')), 'Doxyfile*')
     print(f'Found Doxyfiles:{doxyfiles}')
 
     # targets are judged from Doxyfile name
diff --git a/tools/ci/sg_rules/recommend_way_to_use_soc_caps.yml b/tools/ci/sg_rules/recommend_way_to_use_soc_caps.yml
new file mode 100644
index 0000000000..5435f3055a
--- /dev/null
+++ b/tools/ci/sg_rules/recommend_way_to_use_soc_caps.yml
@@ -0,0 +1,17 @@
+# Refer to https://ast-grep.github.io/guide/rule-config.html for Rule Essentials
+id: recommended-way-to-use-soc-caps
+message: Don't expand SOC_CAPS macro manually
+severity: error # error, warning, info, hint
+note: Should use the macro functions offered by soc_caps_eval.h to compute the SOC_CAPS macro
+language: C
+files:
+  - "components/**/*"
+  - "examples/**/*"
+ignores:
+  - "components/soc/**/soc_caps.h"
+  - "components/soc/**/soc_caps_full.h"
+  - "components/soc/**/soc_caps_eval.h"
+rule:
+  kind: identifier
+  pattern: $A
+  regex: "^_SOC_CAPS_"