mirror of
https://github.com/espressif/esp-idf.git
synced 2026-01-15 16:33:32 +00:00
444 lines
18 KiB
C
444 lines
18 KiB
C
/*
|
||
* SPDX-FileCopyrightText: 2017-2026 Espressif Systems (Shanghai) CO LTD
|
||
*
|
||
* SPDX-License-Identifier: Apache-2.0
|
||
*/
|
||
|
||
#pragma once
|
||
|
||
/**
|
||
* @file esp_timer.h
|
||
* @brief microsecond-precision 64-bit timer API, replacement for ets_timer
|
||
*
|
||
* esp_timer APIs allow components to receive callbacks when a hardware timer
|
||
* reaches certain value. The timer provides microsecond accuracy and
|
||
* up to 64 bit range. Note that while the timer itself provides microsecond
|
||
* accuracy, callbacks are dispatched from an auxiliary task. Some time is
|
||
* needed to notify this task from timer ISR, and then to invoke the callback.
|
||
* If more than one callback needs to be dispatched at any particular time,
|
||
* each subsequent callback will be dispatched only when the previous callback
|
||
* returns. Therefore, callbacks should not do much work; instead, they should
|
||
* use RTOS notification mechanisms (queues, semaphores, event groups, etc.) to
|
||
* pass information to other tasks.
|
||
*
|
||
* To be implemented: it should be possible to request the callback to be called
|
||
* directly from the ISR. This reduces the latency, but has potential impact on
|
||
* all other callbacks which need to be dispatched. This option should only be
|
||
* used for simple callback functions, which do not take longer than a few
|
||
* microseconds to run.
|
||
*
|
||
* Timer callbacks are called from a task running on CPU0.
|
||
* On chips with multiple cores, CPU0 (default) can be changed using
|
||
* the Kconfig option CONFIG_ESP_TIMER_TASK_AFFINITY.
|
||
*/
|
||
|
||
#include <stdint.h>
|
||
#include <stdio.h>
|
||
#include <stdbool.h>
|
||
#include "esp_err.h"
|
||
#include "esp_etm.h"
|
||
#include "sdkconfig.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/**
|
||
* @brief Opaque type representing a single timer handle
|
||
*/
|
||
typedef struct esp_timer* esp_timer_handle_t;
|
||
|
||
/**
|
||
* @brief Timer callback function type
|
||
* @param arg pointer to opaque user-specific data
|
||
*/
|
||
typedef void (*esp_timer_cb_t)(void* arg);
|
||
|
||
/**
|
||
* @brief Method to dispatch timer callback
|
||
*/
|
||
typedef enum {
|
||
ESP_TIMER_TASK, //!< Callback is dispatched from esp_timer task
|
||
#if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD || __DOXYGEN__
|
||
ESP_TIMER_ISR, //!< Callback is dispatched from interrupt handler
|
||
#endif
|
||
ESP_TIMER_MAX, //!< Sentinel value for the number of callback dispatch methods
|
||
} esp_timer_dispatch_t;
|
||
|
||
/**
|
||
* @brief Timer configuration passed to esp_timer_create()
|
||
*/
|
||
typedef struct {
|
||
esp_timer_cb_t callback; //!< Callback function to execute when timer expires
|
||
void* arg; //!< Argument to pass to callback
|
||
esp_timer_dispatch_t dispatch_method; //!< Dispatch callback from task or ISR; if not specified, esp_timer task
|
||
// !< is used; for ISR to work, also set Kconfig option
|
||
// !< `CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD`
|
||
const char* name; //!< Timer name, used in esp_timer_dump() function
|
||
bool skip_unhandled_events; //!< Setting to skip unhandled events in light sleep for periodic timers
|
||
} esp_timer_create_args_t;
|
||
|
||
/**
|
||
* @brief Minimal initialization of esp_timer
|
||
*
|
||
* @note This function is called from startup code. Applications do not need
|
||
* to call this function before using other esp_timer APIs.
|
||
*
|
||
* This function can be called very early in startup process, after this call
|
||
* only esp_timer_get_time() function can be used.
|
||
*
|
||
* @return
|
||
* - ESP_OK on success
|
||
*/
|
||
esp_err_t esp_timer_early_init(void);
|
||
|
||
/**
|
||
* @brief Initialize esp_timer library
|
||
*
|
||
* @note This function is called from startup code. Applications do not need
|
||
* to call this function before using other esp_timer APIs.
|
||
* Before calling this function, esp_timer_early_init() must be called by the
|
||
* startup code.
|
||
*
|
||
* This function will be called from startup code on every core.
|
||
* If Kconfig option `CONFIG_ESP_TIMER_ISR_AFFINITY` is set to `NO_AFFINITY`,
|
||
* it allocates the timer ISR on MULTIPLE cores and
|
||
* creates the timer task which can be run on any core.
|
||
*
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_NO_MEM if allocation has failed
|
||
* - ESP_ERR_INVALID_STATE if already initialized
|
||
* - other errors from interrupt allocator
|
||
*/
|
||
esp_err_t esp_timer_init(void);
|
||
|
||
/**
|
||
* @brief De-initialize esp_timer library
|
||
*
|
||
* @note Normally this function should not be called from applications
|
||
*
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_STATE if not yet initialized
|
||
*/
|
||
esp_err_t esp_timer_deinit(void);
|
||
|
||
/**
|
||
* @brief Create an esp_timer instance
|
||
*
|
||
* @note When timer no longer needed, delete it using esp_timer_delete().
|
||
*
|
||
* @param create_args Pointer to a structure with timer creation arguments.
|
||
* Not saved by the library, can be allocated on the stack.
|
||
* @param[out] out_handle Output, pointer to esp_timer_handle_t variable that
|
||
* holds the created timer handle.
|
||
*
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if some of the create_args are not valid
|
||
* - ESP_ERR_INVALID_STATE if esp_timer library is not initialized yet
|
||
* - ESP_ERR_NO_MEM if memory allocation fails
|
||
*/
|
||
esp_err_t esp_timer_create(const esp_timer_create_args_t* create_args,
|
||
esp_timer_handle_t* out_handle);
|
||
|
||
/**
|
||
* @brief Start a one-shot timer
|
||
*
|
||
* Timer represented by `timer` should not be running when this function is called.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param timeout_us timer timeout, in microseconds relative to the current moment
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the handle is invalid
|
||
* - ESP_ERR_INVALID_STATE if the timer is already running
|
||
*/
|
||
esp_err_t esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us);
|
||
|
||
/**
|
||
* @brief Start a one-shot timer with absolute alarm time
|
||
*
|
||
* This function starts a one-shot timer that will trigger once at the specified absolute time.
|
||
* To start a timer relative to the current time, see esp_timer_start_once().
|
||
* Timer represented by `timer` should not be running when this function is
|
||
* called.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param alarm_us timer alarm time, in absolute microseconds (as returned by esp_timer_get_time())
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the handle is invalid
|
||
* - ESP_ERR_INVALID_STATE if the timer is already running or in the past
|
||
*/
|
||
esp_err_t esp_timer_start_once_at(esp_timer_handle_t timer, uint64_t alarm_us);
|
||
|
||
/**
|
||
* @brief Start a periodic timer
|
||
*
|
||
* Timer represented by `timer` should not be running when this function is called.
|
||
* This function starts the timer which will trigger every `period` microseconds.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param period timer period, in microseconds
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the handle is invalid
|
||
* - ESP_ERR_INVALID_STATE if the timer is already running
|
||
*/
|
||
esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period);
|
||
|
||
/**
|
||
* @brief Start a periodic timer with absolute alarm time
|
||
*
|
||
* Timer represented by `timer` should not be running when this function is called.
|
||
* This function starts the timer which will trigger every `period` microseconds.
|
||
* The first alarm will be triggered at `first_alarm_us` time.
|
||
* To start a periodic timer relative to the current time, see esp_timer_start_periodic().
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param period_us timer period, in microseconds
|
||
* @param first_alarm_us timer first alarm time, in absolute microseconds (as returned by esp_timer_get_time())
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the handle is invalid
|
||
* - ESP_ERR_INVALID_STATE if the timer is already running or in the past
|
||
*/
|
||
esp_err_t esp_timer_start_periodic_at(esp_timer_handle_t timer, uint64_t period_us, uint64_t first_alarm_us);
|
||
|
||
/**
|
||
* @brief Restart a currently running timer
|
||
*
|
||
* Type of `timer` | Action
|
||
* --------------- | ------
|
||
* One-shot timer | Restarted immediately and times out once in `timeout_us` microseconds
|
||
* Periodic timer | Restarted immediately with a new period of `timeout_us` microseconds
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param timeout_us Timeout in microseconds relative to the current time.
|
||
* In case of a periodic timer, also represents the new period.
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the handle is invalid
|
||
* - ESP_ERR_INVALID_STATE if the timer is not running
|
||
*/
|
||
esp_err_t esp_timer_restart(esp_timer_handle_t timer, uint64_t timeout_us);
|
||
|
||
/**
|
||
* @brief Restart a currently running timer with absolute alarm time
|
||
*
|
||
* Type of `timer` | Action
|
||
* --------------- | ------
|
||
* One-shot timer | Restarted immediately and times out once at `alarm_us` microseconds
|
||
* Periodic timer | Restarted immediately with a new period of `period_us` microseconds. Next alarm is at `first_alarm_us` microseconds
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param period_us In case of a periodic timer, represents the new period.
|
||
* @param first_alarm_us timer alarm time, in absolute microseconds (as returned by esp_timer_get_time())
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the handle is invalid
|
||
* - ESP_ERR_INVALID_STATE if the timer is not running or in the past
|
||
*/
|
||
esp_err_t esp_timer_restart_at(esp_timer_handle_t timer, uint64_t period_us, uint64_t first_alarm_us);
|
||
|
||
/**
|
||
* @brief Stop a running timer
|
||
*
|
||
* This function stops the timer previously started using esp_timer_start_once()
|
||
* or esp_timer_start_periodic().
|
||
*
|
||
* This function disarms the timer (prevents future callbacks) but does NOT
|
||
* preempt an already-dispatched or currently-running callback.
|
||
*
|
||
* For a hard guarantee that no callback is running or will run after stop,
|
||
* use esp_timer_stop_blocking() or poll esp_timer_is_active() until it returns false.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_STATE if the timer is not running
|
||
*/
|
||
esp_err_t esp_timer_stop(esp_timer_handle_t timer);
|
||
|
||
/**
|
||
* @brief Stop a running timer and wait for any in-flight callback to complete
|
||
*
|
||
* This function disarms the timer (prevents future callbacks). If the timer callback is
|
||
* currently executing, it waits for the callback to finish, taking into account the specified waiting time.
|
||
*
|
||
* If this function returns ESP_OK, the caller is guaranteed that the timer is disarmed and
|
||
* no callback is executing after the function returns (see the calling-context rules below).
|
||
*
|
||
* @note Behavior depends on calling context:
|
||
* - **User task context (normal case)**: Disarms the timer and waits up to timeout_ticks
|
||
* for any in-flight callback to complete. Returns ESP_OK when no callback is running,
|
||
* or ESP_ERR_TIMEOUT if the callback didn't finish in time.
|
||
*
|
||
* - **ISR context**: Never blocks. Disarms the timer and returns immediately.
|
||
* If the timer callback may still be running, returns ESP_ERR_NOT_FINISHED.
|
||
*
|
||
* - **Callback context**: Disarms the timer and returns immediately. Blocking from a callback
|
||
* would delay the esp_timer task and distort timing of other TASK-dispatch timers.
|
||
* Return value depends on the stopped timer state and the currently running callback:
|
||
* - Returns ESP_OK when the stop request is issued from the stopped timer’s own callback
|
||
* (the callback will complete naturally after it returns).
|
||
* - Returns ESP_ERR_NOT_FINISHED when stopping an ISR-dispatch timer from a foreign callback
|
||
* (i.e., the currently running callback belongs to another timer). In this case the caller
|
||
* cannot safely wait for ISR context to complete, so it is informed that the callback may
|
||
* still be running.
|
||
*
|
||
* If ESP_ERR_NOT_FINISHED is returned, it means that the timer is disarmed, but its callback
|
||
* may is still running or will run soon. In this case, you can wait for the callback to complete
|
||
* using esp_timer_is_active().
|
||
*
|
||
* @param timer Timer handle created using esp_timer_create()
|
||
* @param timeout_ticks Maximum time to wait for callback completion, in FreeRTOS ticks.
|
||
* Use portMAX_DELAY to wait indefinitely.
|
||
* @return
|
||
* - ESP_OK on success (timer is disarmed, no callback is running or will run)
|
||
* - ESP_ERR_TIMEOUT if the callback didn't complete within timeout_ticks
|
||
* - ESP_ERR_INVALID_ARG if the timer handle is invalid
|
||
* - ESP_ERR_INVALID_STATE if esp_timer is not initialized
|
||
* - ESP_ERR_NOT_FINISHED if the callback may still be running (e.g., ISR context, or TIMER_TASK while an ISR callback is in-flight)
|
||
*/
|
||
esp_err_t esp_timer_stop_blocking(esp_timer_handle_t timer, uint32_t timeout_ticks);
|
||
|
||
/**
|
||
* @brief Delete an esp_timer instance
|
||
*
|
||
* The timer must be stopped before deleting. A one-shot timer which has expired
|
||
* does not need to be stopped.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_STATE if the timer is running
|
||
*/
|
||
esp_err_t esp_timer_delete(esp_timer_handle_t timer);
|
||
|
||
/**
|
||
* @brief Get time in microseconds since boot
|
||
* @return Number of microseconds since the initialization of ESP Timer
|
||
*/
|
||
int64_t esp_timer_get_time(void);
|
||
|
||
/**
|
||
* @brief Get the timestamp of the next expected timeout
|
||
* @return Timestamp of the nearest timer event, in microseconds.
|
||
* The timebase is the same as for the values returned by esp_timer_get_time().
|
||
*/
|
||
int64_t esp_timer_get_next_alarm(void);
|
||
|
||
/**
|
||
* @brief Get the timestamp of the next expected timeout excluding those timers
|
||
* that should not interrupt light sleep (such timers have
|
||
* ::esp_timer_create_args_t::skip_unhandled_events enabled)
|
||
* @return Timestamp of the nearest timer event, in microseconds.
|
||
* The timebase is the same as for the values returned by esp_timer_get_time().
|
||
*/
|
||
int64_t esp_timer_get_next_alarm_for_wake_up(void);
|
||
|
||
/**
|
||
* @brief Get the period of a timer
|
||
*
|
||
* This function fetches the timeout period of a timer.
|
||
* For a one-shot timer, the timeout period will be 0.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param period memory to store the timer period value in microseconds
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the arguments are invalid
|
||
*/
|
||
esp_err_t esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period);
|
||
|
||
/**
|
||
* @brief Get the expiry time of a one-shot timer
|
||
*
|
||
* This function fetches the expiry time of a one-shot timer.
|
||
*
|
||
* @note Passing the timer handle of a periodic timer will result in an error.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @param expiry memory to store the timeout value in microseconds
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_INVALID_ARG if the arguments are invalid
|
||
* - ESP_ERR_NOT_SUPPORTED if the timer type is periodic
|
||
*/
|
||
esp_err_t esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry);
|
||
|
||
/**
|
||
* @brief Dump the list of timers to a stream
|
||
*
|
||
* By default, this function prints the list of active (running) timers. The output format is:
|
||
*
|
||
* | Name | Period | Alarm |
|
||
*
|
||
* - Name — timer pointer
|
||
* - Period — period of timer in microseconds, or 0 for one-shot timer
|
||
* - Alarm - time of the next alarm in microseconds since boot, or 0 if the timer is not started
|
||
*
|
||
* To print the list of all created timers, enable Kconfig option `CONFIG_ESP_TIMER_PROFILING`.
|
||
* In this case, the output format is:
|
||
*
|
||
* | Name | Period | Alarm | Times_armed | Times_trigg | Times_skip | Cb_exec_time |
|
||
*
|
||
* - Name — timer name
|
||
* - Period — same as above
|
||
* - Alarm — same as above
|
||
* - Times_armed — number of times the timer was armed via esp_timer_start_X
|
||
* - Times_triggered - number of times the callback was triggered
|
||
* - Times_skipped - number of times the callback was skipped
|
||
* - Callback_exec_time - total time taken by callback to execute, across all calls
|
||
*
|
||
* @param stream stream (such as stdout) to which to dump the information
|
||
* @return
|
||
* - ESP_OK on success
|
||
* - ESP_ERR_NO_MEM if can not allocate temporary buffer for the output
|
||
*/
|
||
esp_err_t esp_timer_dump(FILE* stream);
|
||
|
||
#if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD || defined __DOXYGEN__
|
||
/**
|
||
* @brief Requests a context switch from a timer callback function.
|
||
*
|
||
* This only works for a timer that has an ISR dispatch method.
|
||
* The context switch will be called after all ISR dispatch timers have been processed.
|
||
*/
|
||
void esp_timer_isr_dispatch_need_yield(void);
|
||
#endif // CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD || defined __DOXYGEN__
|
||
|
||
/**
|
||
* @brief Returns status of a timer, active or not
|
||
*
|
||
* This function is used to identify if the timer is still active (running) or not.
|
||
*
|
||
* @param timer timer handle created using esp_timer_create()
|
||
* @return
|
||
* - 1 if timer is still active (running)
|
||
* - 0 if timer is not active
|
||
*/
|
||
bool esp_timer_is_active(esp_timer_handle_t timer);
|
||
|
||
/**
|
||
* @brief Get the ETM event handle of esp_timer underlying alarm event
|
||
*
|
||
* @note The created ETM event object can be deleted later using esp_etm_del_event()
|
||
*
|
||
* @note The ETM event is generated by the underlying hardware - systimer;
|
||
* therefore, if the esp_timer is not clocked by systimer, then no ETM event will be generated.
|
||
*
|
||
* @param[out] out_event Returned ETM event handle
|
||
* @return
|
||
* - ESP_OK Success
|
||
* - ESP_ERR_INVALID_ARG Parameter error
|
||
*/
|
||
esp_err_t esp_timer_new_etm_alarm_event(esp_etm_event_handle_t *out_event);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|