Merge branch 'refactor/esp_driver_ana_cmpr' into 'master'

refactor(ana_cmpr): make analog comparator driver as component

Closes IDF-8521

See merge request espressif/esp-idf!27029

components/driver/CMakeLists.txt

@@ -10,7 +10,6 @@ set(srcs)
 # Always included headers
 set(includes "include"
              "deprecated"
-             "analog_comparator/include"
              "dac/include"
              "i2c/include"
              "i2s/include"
@@ -38,14 +37,6 @@ if(CONFIG_SOC_ADC_DMA_SUPPORTED)
     list(APPEND srcs "deprecated/adc_dma_legacy.c")
 endif()
 
-# Analog comparator related source files
-if(CONFIG_SOC_ANA_CMPR_SUPPORTED)
-    list(APPEND srcs "analog_comparator/ana_cmpr.c")
-    if(CONFIG_SOC_ANA_CMPR_SUPPORT_ETM)
-        list(APPEND srcs "analog_comparator/ana_cmpr_etm.c")
-    endif()
-endif()
-
 # DAC related source files
 if(CONFIG_SOC_DAC_SUPPORTED)
     list(APPEND srcs "dac/dac_oneshot.c"
@@ -192,7 +183,7 @@ else()
                            # for backward compatibility, the driver component needs to
                            # have a public dependency on other "esp_driver_foo" components
                                     esp_driver_gpio esp_driver_pcnt esp_driver_gptimer esp_driver_spi esp_driver_mcpwm
-                                    esp_driver_sdmmc
+                                    esp_driver_sdmmc esp_driver_ana_cmpr
                            LDFRAGMENTS ${ldfragments}
                           )
 endif()

components/driver/Kconfig

@@ -120,31 +120,6 @@ menu "Driver Configurations"
                 Note that, this option only controls the SDM driver log, won't affect other drivers.
     endmenu # Sigma Delta Modulator Configuration
 
-    menu "Analog Comparator Configuration"
-        depends on SOC_ANA_CMPR_SUPPORTED
-        config ANA_CMPR_ISR_IRAM_SAFE
-            bool "Analog comparator ISR IRAM-Safe"
-            default n
-            help
-                Ensure the Analog Comparator interrupt is IRAM-Safe by allowing the interrupt handler to be
-                executable when the cache is disabled (e.g. SPI Flash write).
-
-        config ANA_CMPR_CTRL_FUNC_IN_IRAM
-            bool "Place Analog Comparator control functions into IRAM"
-            default n
-            help
-                Place Analog Comparator control functions (like ana_cmpr_set_internal_reference) into IRAM,
-                so that these functions can be IRAM-safe and able to be called in an IRAM interrupt context.
-                Enabling this option can improve driver performance as well.
-
-        config ANA_CMPR_ENABLE_DEBUG_LOG
-            bool "Enable debug log"
-            default n
-            help
-                Wether to enable the debug log message for Analog Comparator driver.
-                Note that, this option only controls the Analog Comparator driver log, won't affect other drivers.
-    endmenu # Analog Comparator Configuration
-
     orsource "./rmt/Kconfig.rmt"
 
     menu "I2S Configuration"

components/driver/linker.lf

@@ -3,10 +3,6 @@ archive: libdriver.a
 entries:
     if SDM_CTRL_FUNC_IN_IRAM = y:
         sdm: sdm_channel_set_pulse_density (noflash)
-    if ANA_CMPR_CTRL_FUNC_IN_IRAM = y:
-        ana_cmpr: ana_cmpr_set_internal_reference (noflash)
-        ana_cmpr: ana_cmpr_set_debounce (noflash)
-        ana_cmpr: ana_cmpr_set_cross_type (noflash)
     if DAC_CTRL_FUNC_IN_IRAM = y:
         dac_oneshot: dac_oneshot_output_voltage (noflash)
         dac_continuous: dac_continuous_write_asynchronously (noflash)

components/driver/test_apps/.build-test-rules.yml

@@ -1,13 +1,5 @@
 # Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
 
-components/driver/test_apps/analog_comparator:
-  disable:
-    - if: SOC_ANA_CMPR_SUPPORTED != 1
-  disable_test:
-    - if: IDF_TARGET == "esp32p4"
-      temporary: true
-      reason: not supported yet
-
 components/driver/test_apps/dac_test_apps/dac:
   disable:
     - if: SOC_DAC_SUPPORTED != 1

components/esp_driver_ana_cmpr/CMakeLists.txt

@@ -0,0 +1,15 @@
+set(srcs)
+
+# Analog comparator related source files
+if(CONFIG_SOC_ANA_CMPR_SUPPORTED)
+    list(APPEND srcs "ana_cmpr.c")
+    if(CONFIG_SOC_ANA_CMPR_SUPPORT_ETM)
+        list(APPEND srcs "ana_cmpr_etm.c")
+    endif()
+endif()
+
+idf_component_register(SRCS ${srcs}
+                           INCLUDE_DIRS "include"
+                           PRIV_REQUIRES esp_pm esp_driver_gpio
+                           LDFRAGMENTS "linker.lf"
+                          )

components/esp_driver_ana_cmpr/Kconfig

@@ -0,0 +1,24 @@
+menu "ESP-Driver:Analog Comparator Configurations"
+    depends on SOC_ANA_CMPR_SUPPORTED
+    config ANA_CMPR_ISR_IRAM_SAFE
+        bool "Analog comparator ISR IRAM-Safe"
+        default n
+        help
+            Ensure the Analog Comparator interrupt is IRAM-Safe by allowing the interrupt handler to be
+            executable when the cache is disabled (e.g. SPI Flash write).
+
+    config ANA_CMPR_CTRL_FUNC_IN_IRAM
+        bool "Place Analog Comparator control functions into IRAM"
+        default n
+        help
+            Place Analog Comparator control functions (like ana_cmpr_set_internal_reference) into IRAM,
+            so that these functions can be IRAM-safe and able to be called in an IRAM interrupt context.
+            Enabling this option can improve driver performance as well.
+
+    config ANA_CMPR_ENABLE_DEBUG_LOG
+        bool "Enable debug log"
+        default n
+        help
+            Wether to enable the debug log message for Analog Comparator driver.
+            Note that, this option only controls the Analog Comparator driver log, won't affect other drivers.
+endmenu # Analog Comparator Configuration

components/esp_driver_ana_cmpr/ana_cmpr.c

@@ -63,7 +63,7 @@ static const char *TAG = "ana_cmpr";
 
 /* Global static object of the Analog Comparator unit */
 static ana_cmpr_handle_t s_ana_cmpr[SOC_ANA_CMPR_NUM] = {
-    [0 ... (SOC_ANA_CMPR_NUM - 1)] = NULL,
+    [0 ...(SOC_ANA_CMPR_NUM - 1)] = NULL,
 };
 
 /* Global spin lock */
@@ -149,9 +149,9 @@ esp_err_t ana_cmpr_new_unit(const ana_cmpr_config_t *config, ana_cmpr_handle_t *
 
     /* Analog clock comes from IO MUX, but IO MUX clock might be shared with other submodules as well */
     ESP_GOTO_ON_ERROR(esp_clk_tree_src_get_freq_hz((soc_module_clk_t)config->clk_src,
-                                                ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED,
-                                                &s_ana_cmpr[unit]->src_clk_freq_hz),
-                                                err, TAG, "get source clock frequency failed");
+                                                   ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED,
+                                                   &s_ana_cmpr[unit]->src_clk_freq_hz),
+                      err, TAG, "get source clock frequency failed");
     ESP_GOTO_ON_ERROR(io_mux_set_clock_source((soc_module_clk_t)(config->clk_src)), err, TAG,
                       "potential clock source conflicts from other IOMUX peripherals");
 
@@ -298,7 +298,7 @@ esp_err_t ana_cmpr_register_event_callbacks(ana_cmpr_handle_t cmpr, const ana_cm
         intr_flags |= ESP_INTR_FLAG_SHARED;
 #endif  // SOC_ANA_CMPR_INTR_SHARE_WITH_GPIO
         ESP_RETURN_ON_ERROR(esp_intr_alloc_intrstatus(ana_cmpr_periph[cmpr->unit].intr_src, intr_flags, (uint32_t)analog_cmpr_ll_get_intr_status_reg(cmpr->dev),
-                        cmpr->intr_mask, s_ana_cmpr_default_intr_handler, cmpr, &cmpr->intr_handle), TAG, "allocate interrupt failed");
+                                                      cmpr->intr_mask, s_ana_cmpr_default_intr_handler, cmpr, &cmpr->intr_handle), TAG, "allocate interrupt failed");
     }
 
     /* Save the callback group */

components/esp_driver_ana_cmpr/include/driver/ana_cmpr.h

@@ -31,7 +31,7 @@ typedef struct {
     int                     intr_priority;      /*!< The interrupt priority, range 0~7, if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3)
                                                  *   otherwise the larger the higher, 7 is NMI */
     struct {
-        uint32_t            io_loop_back:1;     /*!< Enable this field when the other signals that output on the comparision pins are supposed to be fed back.
+        uint32_t            io_loop_back: 1;     /*!< Enable this field when the other signals that output on the comparision pins are supposed to be fed back.
                                                  *   Normally used for debug/test scenario */
     } flags;                                    /*!< Analog comparator driver flags */
 } ana_cmpr_config_t;

components/esp_driver_ana_cmpr/include/driver/ana_cmpr_types.h

@@ -105,7 +105,7 @@ typedef struct {
  *
  * @return Whether a high priority task has been waken up by this callback function
  */
-typedef bool (*ana_cmpr_cross_cb_t) (ana_cmpr_handle_t cmpr, const ana_cmpr_cross_event_data_t *edata, void *user_ctx);
+typedef bool (*ana_cmpr_cross_cb_t)(ana_cmpr_handle_t cmpr, const ana_cmpr_cross_event_data_t *edata, void *user_ctx);
 
 #ifdef __cplusplus
 }

components/esp_driver_ana_cmpr/linker.lf

@@ -0,0 +1,7 @@
+[mapping:ana_cmpr_driver]
+archive: libesp_driver_ana_cmpr.a
+entries:
+    if ANA_CMPR_CTRL_FUNC_IN_IRAM = y:
+        ana_cmpr: ana_cmpr_set_internal_reference (noflash)
+        ana_cmpr: ana_cmpr_set_debounce (noflash)
+        ana_cmpr: ana_cmpr_set_cross_type (noflash)

components/esp_driver_ana_cmpr/test_apps/.build-test-rules.yml

@@ -0,0 +1,12 @@
+# Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
+
+components/esp_driver_ana_cmpr/test_apps/analog_comparator:
+  disable:
+    - if: SOC_ANA_CMPR_SUPPORTED != 1
+  disable_test:
+    - if: IDF_TARGET == "esp32p4"
+      temporary: true
+      reason: not supported yet
+  depends_components:
+    - esp_driver_gpio
+    - esp_driver_ana_cmpr

components/esp_driver_ana_cmpr/test_apps/analog_comparator/CMakeLists.txt

@@ -10,7 +10,7 @@ project(test_ana_cmpr)
 if(CONFIG_COMPILER_DUMP_RTL_FILES)
     add_custom_target(check_test_app_sections ALL
                       COMMAND ${PYTHON} $ENV{IDF_PATH}/tools/ci/check_callgraph.py
-                      --rtl-dirs ${CMAKE_BINARY_DIR}/esp-idf/driver/,${CMAKE_BINARY_DIR}/esp-idf/hal/
+                      --rtl-dirs ${CMAKE_BINARY_DIR}/esp-idf/esp_driver_ana_cmpr/,${CMAKE_BINARY_DIR}/esp-idf/hal/
                       --elf-file ${CMAKE_BINARY_DIR}/test_ana_cmpr.elf
                       find-refs
                       --from-sections=.iram0.text

components/esp_driver_ana_cmpr/test_apps/analog_comparator/main/CMakeLists.txt

@@ -8,5 +8,5 @@ endif()
 
 idf_component_register(SRCS ${srcs}
                        INCLUDE_DIRS "."
-                       PRIV_REQUIRES unity driver
+                       PRIV_REQUIRES unity esp_driver_gpio esp_driver_ana_cmpr
                        WHOLE_ARCHIVE)

components/esp_hw_support/test_apps/.build-test-rules.yml

@@ -18,7 +18,7 @@ components/esp_hw_support/test_apps/etm:
     - esp_driver_gpio
     - esp_driver_mcpwm
     - esp_timer
-    - driver # TODO: replace with esp_driver_ana_cmpr (IDF-8521)
+    - esp_driver_ana_cmpr
 
 components/esp_hw_support/test_apps/host_test_linux:
   enable:

components/esp_hw_support/test_apps/etm/main/CMakeLists.txt

@@ -29,6 +29,6 @@ endif()
 # In order for the cases defined by `TEST_CASE` to be linked into the final elf,
 # the component can be registered as WHOLE_ARCHIVE
 idf_component_register(SRCS ${srcs}
-                       PRIV_REQUIRES unity esp_timer esp_driver_gptimer esp_driver_gpio esp_driver_mcpwm
-                                     driver # TODO: replace with esp_driver_ana_cmpr (IDF-8521)
+                       PRIV_REQUIRES unity esp_timer esp_driver_gptimer esp_driver_gpio
+                                     esp_driver_mcpwm esp_driver_ana_cmpr
                        WHOLE_ARCHIVE)

docs/doxygen/Doxyfile

@@ -73,9 +73,6 @@ INPUT = \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
     $(PROJECT_PATH)/components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \
     $(PROJECT_PATH)/components/console/esp_console.h \
-    $(PROJECT_PATH)/components/driver/analog_comparator/include/driver/ana_cmpr.h \
-    $(PROJECT_PATH)/components/driver/analog_comparator/include/driver/ana_cmpr_etm.h \
-    $(PROJECT_PATH)/components/driver/analog_comparator/include/driver/ana_cmpr_types.h \
     $(PROJECT_PATH)/components/driver/dac/include/driver/dac_continuous.h \
     $(PROJECT_PATH)/components/driver/dac/include/driver/dac_cosine.h \
     $(PROJECT_PATH)/components/driver/dac/include/driver/dac_oneshot.h \
@@ -124,6 +121,9 @@ INPUT = \
     $(PROJECT_PATH)/components/esp_common/include/esp_check.h \
     $(PROJECT_PATH)/components/esp_common/include/esp_err.h \
     $(PROJECT_PATH)/components/esp_common/include/esp_idf_version.h \
+    $(PROJECT_PATH)/components/esp_driver_ana_cmpr/include/driver/ana_cmpr.h \
+    $(PROJECT_PATH)/components/esp_driver_ana_cmpr/include/driver/ana_cmpr_etm.h \
+    $(PROJECT_PATH)/components/esp_driver_ana_cmpr/include/driver/ana_cmpr_types.h \
     $(PROJECT_PATH)/components/esp_driver_gpio/include/driver/dedic_gpio.h \
     $(PROJECT_PATH)/components/esp_driver_gpio/include/driver/gpio.h \
     $(PROJECT_PATH)/components/esp_driver_gpio/include/driver/gpio_etm.h \

docs/en/migration-guides/release-5.x/5.3/peripherals.rst

@@ -11,6 +11,7 @@ In order to control the dependence of other components on drivers at a smaller g
 - `esp_driver_spi` - Driver for GPSPI
 - `esp_driver_mcpwm` - Driver for Motor Control PWM
 - `esp_driver_sdmmc` - Driver for SDMMC
+- `esp_driver_ana_cmpr` - Driver for Analog Comparator
 
 For compatibility, the original `driver`` component is still treated as an all-in-one component by registering these `esp_driver_xyz`` components as its public dependencies. In other words, you do not need to modify the CMake file of an existing project, but you now have a way to specify the specific peripheral driver that your project depends on.
 

docs/zh_CN/migration-guides/release-5.x/5.3/peripherals.rst

@@ -11,6 +11,7 @@
 - `esp_driver_spi` - 通用 SPI 驱动
 - `esp_driver_mcpwm` - 电机控制 PWM 驱动
 - `esp_driver_sdmmc` - SDMMC 驱动
+- `esp_driver_ana_cmpr` - 模拟比较器驱动
 
 为了兼容性，原来的 `driver` 组件仍然存在，并作为一个 “all-in-one" 的组件，将以上这些 `esp_driver_xyz` 组件注册成自己的公共依赖。换句话说，你无需修改既有项目的 CMake 文件，但是你现在多了一个途径去指定你项目依赖的具体的外设驱动。
 

examples/peripherals/.build-test-rules.yml

@@ -22,6 +22,9 @@ examples/peripherals/analog_comparator:
     - if: IDF_TARGET == "esp32p4"
       temporary: true
       reason: not supported yet
+  depends_components:
+    - esp_driver_gpio
+    - esp_driver_ana_cmpr
 
 examples/peripherals/dac:
   disable:

examples/peripherals/analog_comparator/CMakeLists.txt

@@ -5,4 +5,6 @@
 cmake_minimum_required(VERSION 3.16)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+set(COMPONENTS main)
+
 project(analog_comparator_example)

examples/peripherals/analog_comparator/main/CMakeLists.txt

@@ -7,4 +7,5 @@ else()
 endif()
 
 idf_component_register(SRCS ${src}
+                    PRIV_REQUIRES esp_driver_ana_cmpr esp_driver_gpio
                     INCLUDE_DIRS ".")