feat(timg): graduate the hal driver into a single component

Author: suda-morris

components/bootloader_support/src/bootloader_utility.c

@@ -24,7 +24,6 @@
 #include "soc/rtc.h"
 #include "soc/efuse_periph.h"
 #include "soc/rtc_periph.h"
-#include "soc/timer_periph.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"
 #include "hal/cache_types.h"

components/esp_driver_gptimer/CMakeLists.txt

@@ -14,7 +14,7 @@ if(CONFIG_SOC_TIMER_SUPPORT_ETM)
     list(APPEND srcs "src/gptimer_etm.c")
 endif()
 
-set(requires esp_pm)
+set(requires esp_pm esp_hal_timg)
 
 idf_component_register(SRCS ${srcs}
                        INCLUDE_DIRS ${public_include}

components/esp_driver_gptimer/linker.lf

@@ -12,7 +12,7 @@ entries:
         gptimer: gptimer_stop (noflash)
 
 [mapping:gptimer_hal]
-archive: libhal.a
+archive: libesp_hal_timg.a
 entries:
     if GPTIMER_ISR_HANDLER_IN_IRAM = y:
         timer_hal: timer_hal_capture_and_get_counter_value (noflash)

components/esp_driver_gptimer/src/gptimer_common.c

@@ -50,8 +50,8 @@ gptimer_group_t *gptimer_acquire_group_handle(int group_id)
         // we need to increase/decrease the reference count before enable/disable/reset the peripheral
         PERIPH_RCC_ACQUIRE_ATOMIC(soc_timg_gptimer_signals[group_id][0].parent_module, ref_count) {
             if (ref_count == 0) {
-                timer_ll_enable_bus_clock(group_id, true);
-                timer_ll_reset_register(group_id);
+                timg_ll_enable_bus_clock(group_id, true);
+                timg_ll_reset_register(group_id);
             }
         }
         ESP_LOGD(TAG, "new group (%d) @%p", group_id, group);
@@ -78,7 +78,7 @@ void gptimer_release_group_handle(gptimer_group_t *group)
         // disable bus clock for the timer group
         PERIPH_RCC_RELEASE_ATOMIC(soc_timg_gptimer_signals[group_id][0].parent_module, ref_count) {
             if (ref_count == 0) {
-                timer_ll_enable_bus_clock(group_id, false);
+                timg_ll_enable_bus_clock(group_id, false);
             }
         }
         free(group);

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

@@ -5,3 +5,4 @@ components/esp_driver_gptimer/test_apps/gptimer:
     - if: SOC_GPTIMER_SUPPORTED != 1
   depends_components:
     - esp_driver_gptimer
+    - esp_hal_timg

components/esp_hal_timg/CMakeLists.txt

@@ -0,0 +1,15 @@
+idf_build_get_property(target IDF_TARGET)
+if(${target} STREQUAL "linux")
+    return() # This component is not supported by the POSIX/Linux simulator
+endif()
+
+set(srcs)
+set(public_include "include" "${target}/include")
+
+if(CONFIG_SOC_GPTIMER_SUPPORTED)
+    list(APPEND srcs "timer_hal.c" "${target}/timer_periph.c")
+endif()
+
+idf_component_register(SRCS ${srcs}
+                       INCLUDE_DIRS ${public_include}
+                       REQUIRES soc hal)

components/esp_hal_timg/README.md

@@ -0,0 +1,42 @@
+# ESP Hardware Abstraction Layer for Timer Groups (`esp_hal_timg`)
+
+⚠️ **Notice**: This HAL component is under active development. API stability and backward-compatibility between versions are not guaranteed at this time.
+
+## Overview
+
+The `esp_hal_timg` component provides a **Hardware Abstraction Layer** for the General Purpose Timer peripherals across all ESP-IDF supported targets. It serves as a foundation for the higher-level timer drivers, offering a consistent interface to interact with timer hardware while hiding the complexities of chip-specific implementations.
+
+## Architecture
+
+The HAL architecture consists of two primary layers:
+
+1. **HAL Layer (Upper)**: Defines the operational sequences and data structures required to interact with timer peripherals, including:
+   - Initialization and deinitialization
+   - Timer control operations (start, stop, reload)
+   - Alarm and event handling
+   - Counter operations
+
+2. **Low-Level Layer (Bottom)**: Acts as a translation layer between the HAL and the register definitions in the `soc` component, handling:
+   - Register access abstractions
+   - Chip-specific register configurations
+   - Hardware feature compatibility
+
+## Features
+
+- Unified timer interface across all ESP chip families
+- Support for different timer counting modes (up/down)
+- Alarm functionality with configurable triggers
+- Auto-reload capability
+- ETM (Event Task Matrix) integration on supported chips
+- Multiple clock source options
+
+## Usage
+
+This component is primarily used by ESP-IDF peripheral drivers such as `esp_driver_gptimer`. It is also utilized by system components like `esp_timer`.
+
+For advanced developers implementing custom timer solutions, the HAL functions can be used directly. However, please note that the interfaces provided by this component are internal to ESP-IDF and are subject to change.
+
+## Dependencies
+
+- `soc`: Provides chip-specific register definitions
+- `hal`: Core hardware abstraction utilities and macros

components/esp_hal_timg/esp32/include/hal/lact_ll.h

@@ -0,0 +1,38 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include "hal/assert.h"
+#include "hal/misc.h"
+#include "hal/timg_ll.h"
+#include "soc/timer_group_struct.h"
+#include "soc/dport_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Get timer group register base address with giving group number
+#define LACT_LL_GET_HW(group_id) ((group_id == 0) ? (&TIMERG0) : (&TIMERG1))
+
+/**
+ * @brief Set clock prescale for LACT timer
+ *
+ * @param hw Timer Group register base address
+ * @param divider Prescale value (0 and 1 are not valid)
+ */
+__attribute__((always_inline))
+static inline void lact_ll_set_clock_prescale(timg_dev_t *hw, uint32_t divider)
+{
+    HAL_ASSERT(divider >= 2);
+    HAL_FORCE_MODIFY_U32_REG_FIELD(hw->lactconfig, lact_divider, divider);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32/include/hal/timer_ll.h renamed to components/esp_hal_timg/esp32/include/hal/timer_ll.h

@@ -4,16 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-// Attention: Timer Group has 3 independent functions: General Purpose Timer, Watchdog Timer and Clock calibration.
-//            This Low Level driver only serve the General Purpose Timer function.
-
 #pragma once
 
 #include <stdbool.h>
 #include "esp_attr.h"
 #include "hal/assert.h"
 #include "hal/misc.h"
 #include "hal/timer_types.h"
+#include "hal/timg_ll.h"
 #include "soc/timer_group_struct.h"
 #include "soc/dport_reg.h"
 
@@ -30,61 +28,6 @@ extern "C" {
 // Support APB as function clock
 #define TIMER_LL_FUNC_CLOCK_SUPPORT_APB 1
 
-/**
- * @brief Enable the bus clock for timer group module
- *
- * @param group_id Group ID
- * @param enable true to enable, false to disable
- */
-static inline void _timer_ll_enable_bus_clock(int group_id, bool enable)
-{
-    uint32_t reg_val = DPORT_READ_PERI_REG(DPORT_PERIP_CLK_EN_REG);
-    if (group_id == 0) {
-        reg_val &= ~DPORT_TIMERGROUP_CLK_EN;
-        reg_val |= enable << 13;
-    } else {
-        reg_val &= ~DPORT_TIMERGROUP1_CLK_EN;
-        reg_val |= enable << 15;
-    }
-    DPORT_WRITE_PERI_REG(DPORT_PERIP_CLK_EN_REG, reg_val);
-}
-
-/// use a macro to wrap the function, force the caller to use it in a critical section
-/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
-#define timer_ll_enable_bus_clock(...) do { \
-        (void)__DECLARE_RCC_RC_ATOMIC_ENV; \
-        _timer_ll_enable_bus_clock(__VA_ARGS__); \
-    } while(0)
-
-/**
- * @brief Reset the timer group module
- *
- * @note  After reset the register, the "flash boot protection" will be enabled again.
- *        FLash boot protection is not used anymore after system boot up.
- *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
- *
- * @param group_id Group ID
- */
-static inline void _timer_ll_reset_register(int group_id)
-{
-    if (group_id == 0) {
-        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, DPORT_TIMERGROUP_RST);
-        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, 0);
-        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
-    } else {
-        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, DPORT_TIMERGROUP1_RST);
-        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, 0);
-        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
-    }
-}
-
-/// use a macro to wrap the function, force the caller to use it in a critical section
-/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
-#define timer_ll_reset_register(...) do { \
-        (void)__DECLARE_RCC_RC_ATOMIC_ENV; \
-        _timer_ll_reset_register(__VA_ARGS__); \
-    } while(0)
-
 /**
  * @brief Set clock source for timer
  *
@@ -233,8 +176,8 @@ static inline uint64_t timer_ll_get_counter_value(timg_dev_t *hw, uint32_t timer
 __attribute__((always_inline))
 static inline void timer_ll_set_alarm_value(timg_dev_t *hw, uint32_t timer_num, uint64_t alarm_value)
 {
-    hw->hw_timer[timer_num].alarmhi.tx_alarm_hi = (uint32_t) (alarm_value >> 32);
-    hw->hw_timer[timer_num].alarmlo.tx_alarm_lo = (uint32_t) alarm_value;
+    hw->hw_timer[timer_num].alarmhi.tx_alarm_hi = (uint32_t)(alarm_value >> 32);
+    hw->hw_timer[timer_num].alarmlo.tx_alarm_lo = (uint32_t)alarm_value;
 }
 
 /**
@@ -247,8 +190,8 @@ static inline void timer_ll_set_alarm_value(timg_dev_t *hw, uint32_t timer_num,
 __attribute__((always_inline))
 static inline void timer_ll_set_reload_value(timg_dev_t *hw, uint32_t timer_num, uint64_t load_val)
 {
-    hw->hw_timer[timer_num].loadhi.tx_load_hi = (uint32_t) (load_val >> 32);
-    hw->hw_timer[timer_num].loadlo.tx_load_lo = (uint32_t) load_val;
+    hw->hw_timer[timer_num].loadhi.tx_load_hi = (uint32_t)(load_val >> 32);
+    hw->hw_timer[timer_num].loadlo.tx_load_lo = (uint32_t)load_val;
 }
 
 /**
@@ -343,19 +286,6 @@ static inline volatile void *timer_ll_get_intr_status_reg(timg_dev_t *hw)
     return &hw->int_st_timers.val;
 }
 
-/**
- * @brief Set clock prescale for LACT timer
- *
- * @param hw Timer Group register base address
- * @param timer_num Timer number in the group
- * @param divider Prescale value (0 and 1 are not valid)
- */
-FORCE_INLINE_ATTR void timer_ll_set_lact_clock_prescale(timg_dev_t *hw, uint32_t divider)
-{
-    HAL_ASSERT(divider>=2);
-    HAL_FORCE_MODIFY_U32_REG_FIELD(hw->lactconfig, lact_divider, divider);
-}
-
 #ifdef __cplusplus
 }
 #endif

components/esp_hal_timg/esp32/include/hal/timg_ll.h

@@ -0,0 +1,78 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Attention: Timer Group has 3 independent functions: General Purpose Timer, Watchdog Timer and Clock calibration.
+
+#pragma once
+
+#include <stdbool.h>
+#include "hal/assert.h"
+#include "hal/misc.h"
+#include "soc/timer_group_struct.h"
+#include "soc/dport_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Enable the bus clock for timer group module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void _timg_ll_enable_bus_clock(int group_id, bool enable)
+{
+    uint32_t reg_val = DPORT_READ_PERI_REG(DPORT_PERIP_CLK_EN_REG);
+    if (group_id == 0) {
+        reg_val &= ~DPORT_TIMERGROUP_CLK_EN;
+        reg_val |= enable << 13;
+    } else {
+        reg_val &= ~DPORT_TIMERGROUP1_CLK_EN;
+        reg_val |= enable << 15;
+    }
+    DPORT_WRITE_PERI_REG(DPORT_PERIP_CLK_EN_REG, reg_val);
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timg_ll_enable_bus_clock(...) do { \
+        (void)__DECLARE_RCC_RC_ATOMIC_ENV; \
+        _timg_ll_enable_bus_clock(__VA_ARGS__); \
+    } while(0)
+
+/**
+ * @brief Reset the timer group module
+ *
+ * @note  After reset the register, the "flash boot protection" will be enabled again.
+ *        FLash boot protection is not used anymore after system boot up.
+ *        This function will disable it by default in order to prevent the system from being reset unexpectedly.
+ *
+ * @param group_id Group ID
+ */
+static inline void _timg_ll_reset_register(int group_id)
+{
+    if (group_id == 0) {
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, DPORT_TIMERGROUP_RST);
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, 0);
+        TIMERG0.wdtconfig0.wdt_flashboot_mod_en = 0;
+    } else {
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, DPORT_TIMERGROUP1_RST);
+        DPORT_WRITE_PERI_REG(DPORT_PERIP_RST_EN_REG, 0);
+        TIMERG1.wdtconfig0.wdt_flashboot_mod_en = 0;
+    }
+}
+
+/// use a macro to wrap the function, force the caller to use it in a critical section
+/// the critical section needs to declare the __DECLARE_RCC_RC_ATOMIC_ENV variable in advance
+#define timg_ll_reset_register(...) do { \
+        (void)__DECLARE_RCC_RC_ATOMIC_ENV; \
+        _timg_ll_reset_register(__VA_ARGS__); \
+    } while(0)
+
+#ifdef __cplusplus
+}
+#endif