1 /* 2 * SPDX-FileCopyrightText: 2017-2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 /** 10 * @file private_include/esp_timer_impl.h 11 * 12 * @brief Interface between common and platform-specific parts of esp_timer. 13 * 14 * The functions in this header file are implemented for each supported SoC. 15 * High level functions defined in esp_timer.c call the functions here to 16 * interact with the hardware. 17 */ 18 19 #include <stdint.h> 20 #include "esp_err.h" 21 22 #if defined(CONFIG_SOC_SERIES_ESP32C2) || \ 23 defined(CONFIG_SOC_SERIES_ESP32C3) || \ 24 defined(CONFIG_SOC_SERIES_ESP32C6) 25 #include <zephyr/drivers/interrupt_controller/intc_esp32c3.h> 26 #define ISR_HANDLER isr_handler_t 27 #else 28 #include <zephyr/drivers/interrupt_controller/intc_esp32.h> 29 #define ISR_HANDLER intr_handler_t 30 #endif 31 32 /** 33 * @brief Minimal initialization of platform specific layer of esp_timer 34 * This function can be called very early in startup process, after this call 35 * only esp_timer_get_time function can be used. 36 * esp_timer_impl_init has to be called after this function to initialize the 37 * rest of esp_timer implementation. 38 * @return ESP_OK 39 */ 40 esp_err_t esp_timer_impl_early_init(void); 41 42 /** 43 * @brief Initialize platform specific layer of esp_timer 44 * @param alarm_handler function to call on timer interrupt 45 * Before calling this function, esp_timer_impl_early_init must be called. 46 * @return ESP_OK, ESP_ERR_NO_MEM, or one of the errors from interrupt allocator 47 */ 48 esp_err_t esp_timer_impl_init(ISR_HANDLER alarm_handler); 49 50 /** 51 * @brief Deinitialize platform specific layer of esp_timer 52 */ 53 void esp_timer_impl_deinit(void); 54 55 /** 56 * @brief Set up the timer interrupt to fire at a particular time 57 * 58 * If the alarm time is too close in the future, implementation should set the 59 * alarm to the earliest time possible. 60 * 61 * @param timestamp time in microseconds when interrupt should fire (relative to 62 * boot time, i.e. as returned by esp_timer_impl_get_time) 63 */ 64 void esp_timer_impl_set_alarm(uint64_t timestamp); 65 66 /** 67 * @brief Set up the timer interrupt to fire at a particular time for a particular alarm module. 68 * 69 * If the alarm time is too close in the future, implementation should set the 70 * alarm to the earliest time possible. 71 * 72 * @param timestamp time in microseconds when interrupt should fire (relative to 73 * boot time, i.e. as returned by esp_timer_impl_get_time) 74 * 75 * @param alarm_id Id alarm: 76 * 0 - alarm_0 for the ESP_TIMER_TASK dispatch method, 77 * 1 - alarm_1 for the ESP_TIMER_ISR dispatch method. 78 */ 79 void esp_timer_impl_set_alarm_id(uint64_t timestamp, unsigned alarm_id); 80 81 /** 82 * @brief Notify esp_timer implementation that APB frequency has changed 83 * 84 * Called by the frequency switching code. 85 * 86 * @param apb_ticks_per_us new number of APB clock ticks per microsecond 87 */ 88 void esp_timer_impl_update_apb_freq(uint32_t apb_ticks_per_us); 89 90 /** 91 * @brief Adjust current esp_timer time by a certain value 92 * 93 * Called from light sleep code to synchronize esp_timer time with RTC time. 94 * 95 * @param time_us adjustment to apply to esp_timer time, in microseconds 96 */ 97 void esp_timer_impl_advance(int64_t time_us); 98 99 /** 100 * @brief Get time, in microseconds, since esp_timer_impl_init was called 101 * @return timestamp in microseconds 102 */ 103 int64_t esp_timer_impl_get_time(void); 104 105 /** 106 * @brief Get minimal timer period, in microseconds 107 * Periods shorter than the one returned may not be possible to achieve due to 108 * interrupt latency and context switch time. Short period of periodic timer may 109 * cause the system to spend all the time servicing the interrupt and timer 110 * callback, preventing other tasks from running. 111 * @return minimal period of periodic timer, in microseconds 112 */ 113 uint64_t esp_timer_impl_get_min_period_us(void); 114 115 /** 116 * @brief obtain internal critical section used esp_timer implementation 117 * This can be used when a sequence of calls to esp_timer has to be made, 118 * and it is necessary that the state of the timer is consistent between 119 * the calls. Should be treated in the same way as a spinlock. 120 * Call esp_timer_impl_unlock to release the lock 121 */ 122 void esp_timer_impl_lock(void); 123 124 125 /** 126 * @brief counterpart of esp_timer_impl_lock 127 */ 128 void esp_timer_impl_unlock(void); 129 130 /** 131 * @brief Get counting register 132 * 133 * Bit depth dependents on implementation and can be 32-bit or 64-bit. 134 * 135 * @return the value of the counting register 136 */ 137 uint64_t esp_timer_impl_get_counter_reg(void); 138 139 /** 140 * @brief Get alarm register 141 * 142 * Bit depth dependents on implementation and can be 32-bit or 64-bit. 143 * 144 * @return the value of the alarm register 145 */ 146 uint64_t esp_timer_impl_get_alarm_reg(void); 147 148 #if CONFIG_ESP_TIME_FUNCS_USE_ESP_TIMER 149 /** 150 * @brief Initialize esp_timer as system time provider. 151 */ 152 void esp_timer_impl_init_system_time(void); 153 #endif 154 155 #if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD 156 /** 157 * @brief Set the next alarm if there is such an alarm in the cached array. 158 * 159 * @note Available only when CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD is enabled. 160 */ 161 void esp_timer_impl_try_to_set_next_alarm(void); 162 #endif 163
