gptimer.h

Go to the documentation of this file.

/*****************************************************************************
 *   Copyright(C)2009-2026 by VSF Team                                       *
 *                                                                           *
 *  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.                                           *
 *                                                                           *
 ****************************************************************************/
 
/*
 * Clean-room re-implementation of ESP-IDF public API "driver/gptimer.h"
 * plus its companion "driver/gptimer_types.h", collapsed into a single
 * header for the shim.
 *
 * Authored from ESP-IDF v5.1 public API only. No code copied from the
 * ESP-IDF source tree. The VSF port bridges onto
 *
 *     hal/driver/common/template/vsf_template_timer.h
 *
 * via a caller-supplied pool of vsf_timer_t * instances (see
 *     vsf_espidf_cfg_t::gptimer
 * ).
 *
 * Notes on semantics (v5.1 public contract preserved where feasible):
 *
 *   - gptimer_new_timer() allocates a handle opaquely; the port draws
 *     one vsf_timer_t * from the injected pool. No allocation of VSF
 *     hardware is performed here.
 *   - gptimer_alarm_config_t::alarm_count is interpreted in "resolution
 *     ticks" just like in ESP-IDF: alarm fires when the internal counter
 *     reaches this value. It is wired to vsf_timer_cfg_t::period.
 *   - resolution_hz is wired to vsf_timer_cfg_t::freq (min_freq). The
 *     actual tick frequency depends on the underlying hardware and may
 *     not exactly match the request; ESP-IDF applications that rely on
 *     cycle-accurate timing should cross-check using the counter value
 *     returned by gptimer_get_raw_count() -- which, when the VSF backend
 *     cannot expose it, returns ESP_ERR_NOT_SUPPORTED.
 *   - Clock source selection is accepted but ignored: VSF's timer
 *     abstraction does not surface per-peripheral clock muxing.
 *   - The on_alarm callback's boolean return value is accepted but
 *     ignored -- there is no ISR-to-task yield semantics in the shim.
 */
 
#ifndef __VSF_ESPIDF_DRIVER_GPTIMER_H__
#define __VSF_ESPIDF_DRIVER_GPTIMER_H__
 
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
 
#include "esp_err.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*============================ TYPES =========================================*/
 
typedef struct gptimer_t *gptimer_handle_t;
 
typedef enum {
    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,
} gptimer_clock_source_t;
 
typedef enum {
    GPTIMER_COUNT_DOWN = 0,
    GPTIMER_COUNT_UP   = 1,
} gptimer_count_direction_t;
 
typedef struct {
    gptimer_clock_source_t    clk_src;          
    gptimer_count_direction_t direction;        
    uint32_t                  resolution_hz;    
    int                       intr_priority;    
    struct {
        uint32_t intr_shared : 1;               
        uint32_t backup_before_sleep : 1;       
    } flags;
} gptimer_config_t;
 
typedef struct {
    uint64_t count_value;   
    uint64_t alarm_value;   
} gptimer_alarm_event_data_t;
 
typedef bool (*gptimer_alarm_cb_t)(gptimer_handle_t timer,
                                    const gptimer_alarm_event_data_t *edata,
                                    void *user_ctx);
 
typedef struct {
    gptimer_alarm_cb_t on_alarm;
} gptimer_event_callbacks_t;
 
typedef struct {
    uint64_t alarm_count;
    uint64_t reload_count;
    struct {
        uint32_t auto_reload_on_alarm : 1;
    } flags;
} gptimer_alarm_config_t;
 
/*============================ PROTOTYPES ====================================*/
 
extern esp_err_t gptimer_new_timer(const gptimer_config_t *config,
                                    gptimer_handle_t *ret_timer);
 
extern esp_err_t gptimer_del_timer(gptimer_handle_t timer);
 
extern esp_err_t gptimer_register_event_callbacks(gptimer_handle_t timer,
                                                    const gptimer_event_callbacks_t *cbs,
                                                    void *user_data);
 
extern esp_err_t gptimer_set_alarm_action(gptimer_handle_t timer,
                                            const gptimer_alarm_config_t *config);
 
extern esp_err_t gptimer_enable(gptimer_handle_t timer);
 
extern esp_err_t gptimer_disable(gptimer_handle_t timer);
 
extern esp_err_t gptimer_start(gptimer_handle_t timer);
 
extern esp_err_t gptimer_stop(gptimer_handle_t timer);
 
extern esp_err_t gptimer_set_raw_count(gptimer_handle_t timer, uint64_t value);
 
extern esp_err_t gptimer_get_raw_count(gptimer_handle_t timer, uint64_t *value);
 
extern esp_err_t gptimer_get_resolution(gptimer_handle_t timer,
                                         uint32_t *out_resolution);
 
extern esp_err_t gptimer_get_captured_count(gptimer_handle_t timer,
                                             uint64_t *value);
 
#ifdef __cplusplus
}
#endif
 
#endif      // __VSF_ESPIDF_DRIVER_GPTIMER_H__