// Copyright 2017 Espressif Systems (Shanghai) PTE LTD // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #include #include #include "soc/soc.h" #include "esp_types.h" #include "esp_attr.h" #include "esp_err.h" #include "esp_task.h" #include "esp_log.h" #include "freertos/FreeRTOS.h" #include "freertos/task.h" #include "freertos/semphr.h" #include "freertos/xtensa_api.h" #include "esp_timer.h" #include "esp_timer_impl.h" #include "sdkconfig.h" #ifdef CONFIG_ESP_TIMER_PROFILING #define WITH_PROFILING 1 #endif #ifndef NDEBUG // Enable built-in checks in queue.h in debug builds #define INVARIANTS #endif #include "sys/queue.h" #define EVENT_ID_DELETE_TIMER 0xF0DE1E1E #define TIMER_EVENT_QUEUE_SIZE 16 struct esp_timer { uint64_t alarm; uint64_t period; union { esp_timer_cb_t callback; uint32_t event_id; }; void* arg; #if WITH_PROFILING const char* name; size_t times_triggered; size_t times_armed; uint64_t total_callback_run_time; #endif // WITH_PROFILING LIST_ENTRY(esp_timer) list_entry; }; static bool is_initialized(void); static esp_err_t timer_insert(esp_timer_handle_t timer); static esp_err_t timer_remove(esp_timer_handle_t timer); static bool timer_armed(esp_timer_handle_t timer); static void timer_list_lock(void); static void timer_list_unlock(void); #if WITH_PROFILING static void timer_insert_inactive(esp_timer_handle_t timer); static void timer_remove_inactive(esp_timer_handle_t timer); #endif // WITH_PROFILING static const char* TAG = "esp_timer"; // list of currently armed timers static LIST_HEAD(esp_timer_list, esp_timer) s_timers = LIST_HEAD_INITIALIZER(s_timers); #if WITH_PROFILING // list of unarmed timers, used only to be able to dump statistics about // all the timers static LIST_HEAD(esp_inactive_timer_list, esp_timer) s_inactive_timers = LIST_HEAD_INITIALIZER(s_timers); #endif // task used to dispatch timer callbacks static TaskHandle_t s_timer_task; // counting semaphore used to notify the timer task from ISR static SemaphoreHandle_t s_timer_semaphore; #if CONFIG_SPIRAM_USE_MALLOC // memory for s_timer_semaphore static StaticQueue_t s_timer_semaphore_memory; #endif // lock protecting s_timers, s_inactive_timers static portMUX_TYPE s_timer_lock = portMUX_INITIALIZER_UNLOCKED; esp_err_t esp_timer_create(const esp_timer_create_args_t* args, esp_timer_handle_t* out_handle) { if (!is_initialized()) { return ESP_ERR_INVALID_STATE; } if (args == NULL || args->callback == NULL || out_handle == NULL) { return ESP_ERR_INVALID_ARG; } esp_timer_handle_t result = (esp_timer_handle_t) calloc(1, sizeof(*result)); if (result == NULL) { return ESP_ERR_NO_MEM; } result->callback = args->callback; result->arg = args->arg; #if WITH_PROFILING result->name = args->name; timer_insert_inactive(result); #endif *out_handle = result; return ESP_OK; } esp_err_t IRAM_ATTR esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us) { if (timer == NULL) { return ESP_ERR_INVALID_ARG; } if (!is_initialized() || timer_armed(timer)) { return ESP_ERR_INVALID_STATE; } timer_list_lock(); timer->alarm = esp_timer_get_time() + timeout_us; timer->period = 0; #if WITH_PROFILING timer->times_armed++; #endif esp_err_t err = timer_insert(timer); timer_list_unlock(); return err; } esp_err_t IRAM_ATTR esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period_us) { if (timer == NULL) { return ESP_ERR_INVALID_ARG; } if (!is_initialized() || timer_armed(timer)) { return ESP_ERR_INVALID_STATE; } timer_list_lock(); period_us = MAX(period_us, esp_timer_impl_get_min_period_us()); timer->alarm = esp_timer_get_time() + period_us; timer->period = period_us; #if WITH_PROFILING timer->times_armed++; #endif esp_err_t err = timer_insert(timer); timer_list_unlock(); return err; } esp_err_t IRAM_ATTR esp_timer_stop(esp_timer_handle_t timer) { if (timer == NULL) { return ESP_ERR_INVALID_ARG; } if (!is_initialized() || !timer_armed(timer)) { return ESP_ERR_INVALID_STATE; } return timer_remove(timer); } esp_err_t esp_timer_delete(esp_timer_handle_t timer) { if (timer == NULL) { return ESP_ERR_INVALID_ARG; } if (timer_armed(timer)) { return ESP_ERR_INVALID_STATE; } timer_list_lock(); timer->event_id = EVENT_ID_DELETE_TIMER; timer->alarm = esp_timer_get_time(); timer->period = 0; timer_insert(timer); timer_list_unlock(); return ESP_OK; } static IRAM_ATTR esp_err_t timer_insert(esp_timer_handle_t timer) { #if WITH_PROFILING timer_remove_inactive(timer); #endif esp_timer_handle_t it, last = NULL; if (LIST_FIRST(&s_timers) == NULL) { LIST_INSERT_HEAD(&s_timers, timer, list_entry); } else { LIST_FOREACH(it, &s_timers, list_entry) { if (timer->alarm < it->alarm) { LIST_INSERT_BEFORE(it, timer, list_entry); break; } last = it; } if (it == NULL) { assert(last); LIST_INSERT_AFTER(last, timer, list_entry); } } if (timer == LIST_FIRST(&s_timers)) { esp_timer_impl_set_alarm(timer->alarm); } return ESP_OK; } static IRAM_ATTR esp_err_t timer_remove(esp_timer_handle_t timer) { timer_list_lock(); LIST_REMOVE(timer, list_entry); timer->alarm = 0; timer->period = 0; #if WITH_PROFILING timer_insert_inactive(timer); #endif timer_list_unlock(); return ESP_OK; } #if WITH_PROFILING static IRAM_ATTR void timer_insert_inactive(esp_timer_handle_t timer) { /* May be locked or not, depending on where this is called from. * Lock recursively. */ timer_list_lock(); esp_timer_handle_t head = LIST_FIRST(&s_inactive_timers); if (head == NULL) { LIST_INSERT_HEAD(&s_inactive_timers, timer, list_entry); } else { /* Insert as head element as this is the fastest thing to do. * Removal is O(1) anyway. */ LIST_INSERT_BEFORE(head, timer, list_entry); } timer_list_unlock(); } static IRAM_ATTR void timer_remove_inactive(esp_timer_handle_t timer) { timer_list_lock(); LIST_REMOVE(timer, list_entry); timer_list_unlock(); } #endif // WITH_PROFILING static IRAM_ATTR bool timer_armed(esp_timer_handle_t timer) { return timer->alarm > 0; } static IRAM_ATTR void timer_list_lock(void) { portENTER_CRITICAL_SAFE(&s_timer_lock); } static IRAM_ATTR void timer_list_unlock(void) { portEXIT_CRITICAL_SAFE(&s_timer_lock); } static void timer_process_alarm(esp_timer_dispatch_t dispatch_method) { /* unused, provision to allow running callbacks from ISR */ (void) dispatch_method; timer_list_lock(); int64_t now = esp_timer_impl_get_time(); esp_timer_handle_t it = LIST_FIRST(&s_timers); while (it != NULL && it->alarm < now) { // NOLINT(clang-analyzer-unix.Malloc) // Static analyser reports "Use of memory after it is freed" since the "it" variable // is freed below (if EVENT_ID_DELETE_TIMER) and assigned to the (new) LIST_FIRST() // so possibly (if the "it" hasn't been removed from the list) it might keep the same ptr. // Ignoring this warning, as this couldn't happen if queue.h used to populate the list LIST_REMOVE(it, list_entry); if (it->event_id == EVENT_ID_DELETE_TIMER) { free(it); it = LIST_FIRST(&s_timers); continue; } if (it->period > 0) { it->alarm += it->period; timer_insert(it); } else { it->alarm = 0; #if WITH_PROFILING timer_insert_inactive(it); #endif } #if WITH_PROFILING uint64_t callback_start = now; #endif esp_timer_cb_t callback = it->callback; void* arg = it->arg; timer_list_unlock(); (*callback)(arg); timer_list_lock(); now = esp_timer_impl_get_time(); #if WITH_PROFILING it->times_triggered++; it->total_callback_run_time += now - callback_start; #endif it = LIST_FIRST(&s_timers); } esp_timer_handle_t first = LIST_FIRST(&s_timers); if (first) { esp_timer_impl_set_alarm(first->alarm); } timer_list_unlock(); } static void timer_task(void* arg) { while (true){ int res = xSemaphoreTake(s_timer_semaphore, portMAX_DELAY); assert(res == pdTRUE); timer_process_alarm(ESP_TIMER_TASK); } } static void IRAM_ATTR timer_alarm_handler(void* arg) { int need_yield; if (xSemaphoreGiveFromISR(s_timer_semaphore, &need_yield) != pdPASS) { ESP_EARLY_LOGD(TAG, "timer queue overflow"); return; } if (need_yield == pdTRUE) { portYIELD_FROM_ISR(); } } static IRAM_ATTR bool is_initialized(void) { return s_timer_task != NULL; } esp_err_t esp_timer_init(void) { esp_err_t err; if (is_initialized()) { return ESP_ERR_INVALID_STATE; } #if CONFIG_SPIRAM_USE_MALLOC memset(&s_timer_semaphore_memory, 0, sizeof(StaticQueue_t)); s_timer_semaphore = xSemaphoreCreateCountingStatic(TIMER_EVENT_QUEUE_SIZE, 0, &s_timer_semaphore_memory); #else s_timer_semaphore = xSemaphoreCreateCounting(TIMER_EVENT_QUEUE_SIZE, 0); #endif if (!s_timer_semaphore) { err = ESP_ERR_NO_MEM; goto out; } int ret = xTaskCreatePinnedToCore(&timer_task, "esp_timer", ESP_TASK_TIMER_STACK, NULL, ESP_TASK_TIMER_PRIO, &s_timer_task, PRO_CPU_NUM); if (ret != pdPASS) { err = ESP_ERR_NO_MEM; goto out; } err = esp_timer_impl_init(&timer_alarm_handler); if (err != ESP_OK) { goto out; } return ESP_OK; out: if (s_timer_task) { vTaskDelete(s_timer_task); s_timer_task = NULL; } if (s_timer_semaphore) { vSemaphoreDelete(s_timer_semaphore); s_timer_semaphore = NULL; } return ESP_ERR_NO_MEM; } esp_err_t esp_timer_deinit(void) { if (!is_initialized()) { return ESP_ERR_INVALID_STATE; } /* Check if there are any active timers */ if (!LIST_EMPTY(&s_timers)) { return ESP_ERR_INVALID_STATE; } /* We can only check if there are any timers which are not deleted if * profiling is enabled. */ #if WITH_PROFILING if (!LIST_EMPTY(&s_inactive_timers)) { return ESP_ERR_INVALID_STATE; } #endif esp_timer_impl_deinit(); vTaskDelete(s_timer_task); s_timer_task = NULL; vSemaphoreDelete(s_timer_semaphore); s_timer_semaphore = NULL; return ESP_OK; } static void print_timer_info(esp_timer_handle_t t, char** dst, size_t* dst_size) { size_t cb = snprintf(*dst, *dst_size, #if WITH_PROFILING "%-12s %12lld %12lld %9d %9d %12lld\n", t->name, t->period, t->alarm, t->times_armed, t->times_triggered, t->total_callback_run_time); /* keep this in sync with the format string, used in esp_timer_dump */ #define TIMER_INFO_LINE_LEN 78 #else "timer@%p %12lld %12lld\n", t, t->period, t->alarm); #define TIMER_INFO_LINE_LEN 46 #endif *dst += cb; *dst_size -= cb; } esp_err_t esp_timer_dump(FILE* stream) { /* Since timer lock is a critical section, we don't want to print directly * to stdout, since that may cause a deadlock if stdout is interrupt-driven * (via the UART driver). Allocate sufficiently large chunk of memory first, * print to it, then dump this memory to stdout. */ esp_timer_handle_t it; /* First count the number of timers */ size_t timer_count = 0; timer_list_lock(); LIST_FOREACH(it, &s_timers, list_entry) { ++timer_count; } #if WITH_PROFILING LIST_FOREACH(it, &s_inactive_timers, list_entry) { ++timer_count; } #endif timer_list_unlock(); /* Allocate the memory for this number of timers. Since we have unlocked, * we may find that there are more timers. There's no bulletproof solution * for this (can't allocate from a critical section), but we allocate * slightly more and the output will be truncated if that is not enough. */ size_t buf_size = TIMER_INFO_LINE_LEN * (timer_count + 3); char* print_buf = calloc(1, buf_size + 1); if (print_buf == NULL) { return ESP_ERR_NO_MEM; } /* Print to the buffer */ timer_list_lock(); char* pos = print_buf; LIST_FOREACH(it, &s_timers, list_entry) { print_timer_info(it, &pos, &buf_size); } #if WITH_PROFILING LIST_FOREACH(it, &s_inactive_timers, list_entry) { print_timer_info(it, &pos, &buf_size); } #endif timer_list_unlock(); /* Print the buffer */ fputs(print_buf, stream); free(print_buf); return ESP_OK; } int64_t IRAM_ATTR esp_timer_get_next_alarm(void) { int64_t next_alarm = INT64_MAX; timer_list_lock(); esp_timer_handle_t it = LIST_FIRST(&s_timers); if (it) { next_alarm = it->alarm; } timer_list_unlock(); return next_alarm; }