esp-idf/components/esp_timer/src/esp_timer.c

// 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 <sys/param.h>
#include <string.h>
#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 "soc/spinlock.h"
#include "esp_timer.h"
#include "esp_timer_impl.h"

#include "esp_private/startup_internal.h"
#include "esp_private/esp_timer_private.h"
#include "esp_private/system_internal.h"

#if CONFIG_IDF_TARGET_ESP32
#include "esp32/rtc.h"
#elif CONFIG_IDF_TARGET_ESP32S2
#include "esp32s2/rtc.h"
#endif

#include "sdkconfig.h"

#if defined( CONFIG_ESP32_TIME_SYSCALL_USE_FRC1 ) || \
    defined( CONFIG_ESP32_TIME_SYSCALL_USE_RTC_FRC1 ) || \
    defined( CONFIG_ESP32S2_TIME_SYSCALL_USE_FRC1 ) || \
    defined( CONFIG_ESP32S2_TIME_SYSCALL_USE_RTC_FRC1 )
#define WITH_FRC 1
#endif

#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 inline 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 inline 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;
    }

#if WITH_FRC
    // [refactor-todo] this logic, "esp_rtc_get_time_us() - g_startup_time", is also
    // the weak definition of esp_system_get_time; find a way to remove this duplication.
    esp_timer_private_advance(esp_rtc_get_time_us() - g_startup_time);
#endif

    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;
}

// Provides strong definition for system time functions relied upon
// by core components.
#if WITH_FRC
int64_t IRAM_ATTR esp_system_get_time(void)
{
    return esp_timer_get_time();
}

uint32_t IRAM_ATTR esp_system_get_time_resolution(void)
{
    return 1;
}
#endif