feat(soc): introduce the soc_caps_full.h for internal use only

Author: suda-morris

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)` |

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

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

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

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

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

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

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

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

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