1 // Copyright 2017 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 /** 18 * @file esp_timer.h 19 * @brief microsecond-precision 64-bit timer API, replacement for ets_timer 20 * 21 * esp_timer APIs allow components to receive callbacks when a hardware timer 22 * reaches certain value. The timer provides microsecond accuracy and 23 * up to 64 bit range. Note that while the timer itself provides microsecond 24 * accuracy, callbacks are dispatched from an auxiliary task. Some time is 25 * needed to notify this task from timer ISR, and then to invoke the callback. 26 * If more than one callback needs to be dispatched at any particular time, 27 * each subsequent callback will be dispatched only when the previous callback 28 * returns. Therefore, callbacks should not do much work; instead, they should 29 * use RTOS notification mechanisms (queues, semaphores, event groups, etc.) to 30 * pass information to other tasks. 31 * 32 * To be implemented: it should be possible to request the callback to be called 33 * directly from the ISR. This reduces the latency, but has potential impact on 34 * all other callbacks which need to be dispatched. This option should only be 35 * used for simple callback functions, which do not take longer than a few 36 * microseconds to run. 37 * 38 * Implementation note: on the ESP32, esp_timer APIs use the "legacy" FRC2 39 * timer. Timer callbacks are called from a task running on the PRO CPU. 40 */ 41 42 #include <stdint.h> 43 #include <stdio.h> 44 #include <stdbool.h> 45 #include "esp_err.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Opaque type representing a single esp_timer 53 */ 54 typedef struct esp_timer* esp_timer_handle_t; 55 56 /** 57 * @brief Timer callback function type 58 * @param arg pointer to opaque user-specific data 59 */ 60 typedef void (*esp_timer_cb_t)(void* arg); 61 62 63 /** 64 * @brief Method for dispatching timer callback 65 */ 66 typedef enum { 67 ESP_TIMER_TASK, //!< Callback is called from timer task 68 69 /* Not supported for now, provision to allow callbacks to run directly 70 * from an ISR: 71 72 ESP_TIMER_ISR, //!< Callback is called from timer ISR 73 74 */ 75 } esp_timer_dispatch_t; 76 77 /** 78 * @brief Timer configuration passed to esp_timer_create 79 */ 80 typedef struct { 81 esp_timer_cb_t callback; //!< Function to call when timer expires 82 void* arg; //!< Argument to pass to the callback 83 esp_timer_dispatch_t dispatch_method; //!< Call the callback from task or from ISR 84 const char* name; //!< Timer name, used in esp_timer_dump function 85 bool skip_unhandled_events; //!< Skip unhandled events for periodic timers 86 } esp_timer_create_args_t; 87 88 /** 89 * @brief Initialize esp_timer library 90 * 91 * @note This function is called from startup code. Applications do not need 92 * to call this function before using other esp_timer APIs. 93 * 94 * @return 95 * - ESP_OK on success 96 * - ESP_ERR_NO_MEM if allocation has failed 97 * - ESP_ERR_INVALID_STATE if already initialized 98 * - other errors from interrupt allocator 99 */ 100 esp_err_t esp_timer_init(void); 101 102 /** 103 * @brief De-initialize esp_timer library 104 * 105 * @note Normally this function should not be called from applications 106 * 107 * @return 108 * - ESP_OK on success 109 * - ESP_ERR_INVALID_STATE if not yet initialized 110 */ 111 esp_err_t esp_timer_deinit(void); 112 113 /** 114 * @brief Create an esp_timer instance 115 * 116 * @note When done using the timer, delete it with esp_timer_delete function. 117 * 118 * @param create_args Pointer to a structure with timer creation arguments. 119 * Not saved by the library, can be allocated on the stack. 120 * @param[out] out_handle Output, pointer to esp_timer_handle_t variable which 121 * will hold the created timer handle. 122 * 123 * @return 124 * - ESP_OK on success 125 * - ESP_ERR_INVALID_ARG if some of the create_args are not valid 126 * - ESP_ERR_INVALID_STATE if esp_timer library is not initialized yet 127 * - ESP_ERR_NO_MEM if memory allocation fails 128 */ 129 esp_err_t esp_timer_create(const esp_timer_create_args_t* create_args, 130 esp_timer_handle_t* out_handle); 131 132 /** 133 * @brief Start one-shot timer 134 * 135 * Timer should not be running when this function is called. 136 * 137 * @param timer timer handle created using esp_timer_create 138 * @param timeout_us timer timeout, in microseconds relative to the current moment 139 * @return 140 * - ESP_OK on success 141 * - ESP_ERR_INVALID_ARG if the handle is invalid 142 * - ESP_ERR_INVALID_STATE if the timer is already running 143 */ 144 esp_err_t esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us); 145 146 /** 147 * @brief Start a periodic timer 148 * 149 * Timer should not be running when this function is called. This function will 150 * start the timer which will trigger every 'period' microseconds. 151 * 152 * @param timer timer handle created using esp_timer_create 153 * @param period timer period, in microseconds 154 * @return 155 * - ESP_OK on success 156 * - ESP_ERR_INVALID_ARG if the handle is invalid 157 * - ESP_ERR_INVALID_STATE if the timer is already running 158 */ 159 esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period); 160 161 /** 162 * @brief Stop the timer 163 * 164 * This function stops the timer previously started using esp_timer_start_once 165 * or esp_timer_start_periodic. 166 * 167 * @param timer timer handle created using esp_timer_create 168 * @return 169 * - ESP_OK on success 170 * - ESP_ERR_INVALID_STATE if the timer is not running 171 */ 172 esp_err_t esp_timer_stop(esp_timer_handle_t timer); 173 174 /** 175 * @brief Delete an esp_timer instance 176 * 177 * The timer must be stopped before deleting. A one-shot timer which has expired 178 * does not need to be stopped. 179 * 180 * @param timer timer handle allocated using esp_timer_create 181 * @return 182 * - ESP_OK on success 183 * - ESP_ERR_INVALID_STATE if the timer is running 184 */ 185 esp_err_t esp_timer_delete(esp_timer_handle_t timer); 186 187 /** 188 * @brief Get time in microseconds since boot 189 * @return number of microseconds since esp_timer_init was called (this normally 190 * happens early during application startup). 191 */ 192 int64_t esp_timer_get_time(void); 193 194 /** 195 * @brief Get the timestamp when the next timeout is expected to occur 196 * @return Timestamp of the nearest timer event, in microseconds. 197 * The timebase is the same as for the values returned by esp_timer_get_time. 198 */ 199 int64_t esp_timer_get_next_alarm(void); 200 201 /** 202 * @brief Dump the list of timers to a stream 203 * 204 * If CONFIG_ESP_TIMER_PROFILING option is enabled, this prints the list of all 205 * the existing timers. Otherwise, only the list active timers is printed. 206 * 207 * The format is: 208 * 209 * name period alarm times_armed times_triggered total_callback_run_time 210 * 211 * where: 212 * 213 * name — timer name (if CONFIG_ESP_TIMER_PROFILING is defined), or timer pointer 214 * period — period of timer, in microseconds, or 0 for one-shot timer 215 * alarm - time of the next alarm, in microseconds since boot, or 0 if the timer 216 * is not started 217 * 218 * The following fields are printed if CONFIG_ESP_TIMER_PROFILING is defined: 219 * 220 * times_armed — number of times the timer was armed via esp_timer_start_X 221 * times_triggered - number of times the callback was called 222 * total_callback_run_time - total time taken by callback to execute, across all calls 223 * 224 * @param stream stream (such as stdout) to dump the information to 225 * @return 226 * - ESP_OK on success 227 * - ESP_ERR_NO_MEM if can not allocate temporary buffer for the output 228 */ 229 esp_err_t esp_timer_dump(FILE* stream); 230 231 /** 232 * @brief Returns status of a timer, active or not 233 * 234 * This function is used to identify if the timer is still active or not. 235 * 236 * @param timer timer handle created using esp_timer_create 237 * @return 238 * - 1 if timer is still active 239 * - 0 if timer is not active. 240 */ 241 bool esp_timer_is_active(esp_timer_handle_t timer); 242 243 #ifdef __cplusplus 244 } 245 #endif 246