gptimer.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "esp_err.h"

Go to the source code of this file.

Data Structures
struct	gptimer_config_t
	Initial configuration for gptimer_new_timer(). More...
struct	gptimer_alarm_event_data_t
	Data passed to gptimer_alarm_cb_t at each alarm event. More...
struct	gptimer_event_callbacks_t
	Event callback set attachable via gptimer_register_event_callbacks(). More...
struct	gptimer_alarm_config_t
	Behaviour applied to the counter when the alarm matches. More...

Typedefs
typedef struct gptimer_t *	gptimer_handle_t
	Opaque handle for a general-purpose timer.
typedef bool(*	gptimer_alarm_cb_t) (gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx)
	User callback invoked from the alarm ISR.

Enumerations
enum	gptimer_clock_source_t {   GPTIMER_CLK_SRC_DEFAULT = 0 ,   GPTIMER_CLK_SRC_APB = 1 ,   GPTIMER_CLK_SRC_XTAL = 2 ,   GPTIMER_CLK_SRC_RC_FAST = 3 ,   GPTIMER_CLK_SRC_PLL_F40M = 4 ,   GPTIMER_CLK_SRC_PLL_F80M = 5 }
	Timer clock source. More...
enum	gptimer_count_direction_t {   GPTIMER_COUNT_DOWN = 0 ,   GPTIMER_COUNT_UP = 1 }
	Count direction. More...

Functions
esp_err_t	gptimer_new_timer (const gptimer_config_t *config, gptimer_handle_t *ret_timer)
	Allocate a new gptimer handle drawn from the injected VSF pool.
esp_err_t	gptimer_del_timer (gptimer_handle_t timer)
	Release a gptimer handle, stopping the underlying timer first.
esp_err_t	gptimer_register_event_callbacks (gptimer_handle_t timer, const gptimer_event_callbacks_t *cbs, void *user_data)
	Register the alarm callback (and future per-event callbacks).
esp_err_t	gptimer_set_alarm_action (gptimer_handle_t timer, const gptimer_alarm_config_t *config)
	Configure the alarm action applied at the next alarm event.
esp_err_t	gptimer_enable (gptimer_handle_t timer)
	Transition the timer into the "enabled" state.
esp_err_t	gptimer_disable (gptimer_handle_t timer)
	Transition the timer out of the "enabled" state.
esp_err_t	gptimer_start (gptimer_handle_t timer)
	Start the counter. The timer must already be enabled.
esp_err_t	gptimer_stop (gptimer_handle_t timer)
	Stop the counter. The counter value is retained.
esp_err_t	gptimer_set_raw_count (gptimer_handle_t timer, uint64_t value)
	Set the raw counter value.
esp_err_t	gptimer_get_raw_count (gptimer_handle_t timer, uint64_t *value)
	Read the raw counter value.
esp_err_t	gptimer_get_resolution (gptimer_handle_t timer, uint32_t *out_resolution)
	Query the actual resolution chosen by the underlying hardware.
esp_err_t	gptimer_get_captured_count (gptimer_handle_t timer, uint64_t *value)
	Return the number of alarms that have fired since enable.

Typedef Documentation

gptimer_handle_t

typedef struct gptimer_t* gptimer_handle_t

Opaque handle for a general-purpose timer.

gptimer_alarm_cb_t

typedef bool(* gptimer_alarm_cb_t) (gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx)

User callback invoked from the alarm ISR.

The return value is interpreted by ESP-IDF as "yield to a woken task"; the VSF shim always ignores it.

Enumeration Type Documentation

gptimer_clock_source_t

enum gptimer_clock_source_t

Timer clock source.

The shim accepts every value for source compatibility but ignores the selection: VSF's vsf_timer_t does not expose per-peripheral clock muxing. Whichever source is wired up by the underlying hardware port is used.

Enumerator
GPTIMER_CLK_SRC_DEFAULT
GPTIMER_CLK_SRC_APB
GPTIMER_CLK_SRC_XTAL
GPTIMER_CLK_SRC_RC_FAST
GPTIMER_CLK_SRC_PLL_F40M
GPTIMER_CLK_SRC_PLL_F80M

gptimer_count_direction_t

enum gptimer_count_direction_t

Count direction.

Only GPTIMER_COUNT_UP is supported by the VSF backend. Passing GPTIMER_COUNT_DOWN to gptimer_new_timer() yields ESP_ERR_NOT_SUPPORTED.

Enumerator
GPTIMER_COUNT_DOWN
GPTIMER_COUNT_UP

Function Documentation

gptimer_new_timer()

esp_err_t gptimer_new_timer ( const gptimer_config_t *  config, gptimer_handle_t *  ret_timer  )

extern

Allocate a new gptimer handle drawn from the injected VSF pool.

Return values

ESP_OK	success
ESP_ERR_INVALID_ARG	config / ret_timer is NULL, direction != UP
ESP_ERR_INVALID_STATE	shim not initialised or pool exhausted
ESP_ERR_NO_MEM	heap exhausted for handle metadata

gptimer_del_timer()

esp_err_t gptimer_del_timer ( gptimer_handle_t  timer )

extern

Release a gptimer handle, stopping the underlying timer first.

Return values

ESP_OK	success
ESP_ERR_INVALID_ARG	timer is NULL
ESP_ERR_INVALID_STATE	timer is still in the enabled state

gptimer_register_event_callbacks()

esp_err_t gptimer_register_event_callbacks ( gptimer_handle_t  timer, const gptimer_event_callbacks_t *  cbs, void *  user_data  )

extern

Register the alarm callback (and future per-event callbacks).

Must be called while the timer is in the disabled state – mirroring the ESP-IDF contract that forbids hot-patching callbacks.

gptimer_set_alarm_action()

esp_err_t gptimer_set_alarm_action ( gptimer_handle_t  timer, const gptimer_alarm_config_t *  config  )

extern

Configure the alarm action applied at the next alarm event.

Passing config == NULL disables alarm generation. Otherwise the shim programs the underlying vsf_timer so that an overflow IRQ fires every alarm_count ticks; reload_count is honoured only when the implemented backend exposes a way to pre-load the counter (currently: only auto_reload_on_alarm is supported by mapping to a continuous timer, other combinations fall back to continuous semantics too).

gptimer_enable()

esp_err_t gptimer_enable ( gptimer_handle_t  timer )

extern

Transition the timer into the "enabled" state.

The counter is not yet running; call gptimer_start() to start counting.

gptimer_disable()

esp_err_t gptimer_disable ( gptimer_handle_t  timer )

extern

Transition the timer out of the "enabled" state.

gptimer_start()

esp_err_t gptimer_start ( gptimer_handle_t  timer )

extern

Start the counter. The timer must already be enabled.

gptimer_stop()

esp_err_t gptimer_stop ( gptimer_handle_t  timer )

extern

Stop the counter. The counter value is retained.

gptimer_set_raw_count()

esp_err_t gptimer_set_raw_count ( gptimer_handle_t  timer, uint64_t  value  )

extern

Set the raw counter value.

Return values

ESP_ERR_NOT_SUPPORTED

the VSF backend does not expose this

gptimer_get_raw_count()

esp_err_t gptimer_get_raw_count ( gptimer_handle_t  timer, uint64_t *  value  )

extern

Read the raw counter value.

Return values

ESP_ERR_NOT_SUPPORTED

the VSF backend does not expose this

gptimer_get_resolution()

esp_err_t gptimer_get_resolution ( gptimer_handle_t  timer, uint32_t *  out_resolution  )

extern

Query the actual resolution chosen by the underlying hardware.

May differ from the requested resolution_hz when the clock divider is discrete. The shim returns the value programmed by the backend when available, otherwise the originally requested value.

gptimer_get_captured_count()

esp_err_t gptimer_get_captured_count ( gptimer_handle_t  timer, uint64_t *  value  )

extern

Return the number of alarms that have fired since enable.

Return values

ESP_ERR_NOT_SUPPORTED

the VSF backend does not track this