1 /*
2  * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #include <stdint.h>
10 #include <stdbool.h>
11 #include "hal/systimer_types.h"
12 #include "soc/soc_caps.h"
13 #include "soc/clk_tree_defs.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 typedef struct systimer_dev_t *systimer_soc_handle_t;   // systimer SOC layer handle
20 
21 // the definitions of the following functions are provided by esp_hw_support component, see esp_hw_support/port/${TARGET}/systimer.c
22 typedef uint64_t (*ticks_to_us_func_t)(uint64_t ticks); // prototype of function to convert ticks to microseconds
23 typedef uint64_t (*us_to_ticks_func_t)(uint64_t us);    // prototype of function to convert microseconds to ticks
24 
25 /**
26  * @brief systimer HAL context structure
27  */
28 typedef struct {
29     systimer_soc_handle_t dev;      /*!< systimer peripheral base address */
30     ticks_to_us_func_t ticks_to_us; /*!< function to convert ticks to microseconds */
31     us_to_ticks_func_t us_to_ticks; /*!< function to convert microseconds to ticks */
32 } systimer_hal_context_t;
33 
34 /**
35  * @brief systimer HAL configuration structure
36  */
37 typedef struct {
38     ticks_to_us_func_t ticks_to_us; /*!< function to convert ticks to microseconds */
39     us_to_ticks_func_t us_to_ticks; /*!< function to convert microseconds to ticks */
40 } systimer_hal_tick_rate_ops_t;
41 
42 /**
43  * @brief Systimer clock source
44  */
45 typedef soc_periph_systimer_clk_src_t systimer_clock_source_t;
46 
47 /**
48  * @brief initialize systimer in HAL layer
49  */
50 void systimer_hal_init(systimer_hal_context_t *hal);
51 
52 /**
53  * @brief Deinitialize systimer HAL layer
54  */
55 void systimer_hal_deinit(systimer_hal_context_t *hal);
56 
57 /**
58  * @brief Set tick rate operation functions
59  */
60 void systimer_hal_set_tick_rate_ops(systimer_hal_context_t *hal, systimer_hal_tick_rate_ops_t *ops);
61 
62 /**
63  * @brief enable systimer counter
64  */
65 void systimer_hal_enable_counter(systimer_hal_context_t *hal, uint32_t counter_id);
66 
67 /**
68  * @brief get current counter value
69  */
70 uint64_t systimer_hal_get_counter_value(systimer_hal_context_t *hal, uint32_t counter_id);
71 
72 /**
73  * @brief get current time (in microseconds)
74  */
75 uint64_t systimer_hal_get_time(systimer_hal_context_t *hal, uint32_t counter_id);
76 
77 /*
78  * @brief set alarm target value (used in one-shot mode)
79  */
80 void systimer_hal_set_alarm_target(systimer_hal_context_t *hal, uint32_t alarm_id, uint64_t target);
81 
82 /**
83  * @brief set alarm period value (used in period mode)
84  */
85 void systimer_hal_set_alarm_period(systimer_hal_context_t *hal, uint32_t alarm_id, uint32_t period);
86 
87 /**
88  * @brief get alarm time
89  */
90 uint64_t systimer_hal_get_alarm_value(systimer_hal_context_t *hal, uint32_t alarm_id);
91 
92 /**
93  * @brief enable alarm interrupt
94  */
95 void systimer_hal_enable_alarm_int(systimer_hal_context_t *hal, uint32_t alarm_id);
96 
97 /**
98  * @brief select alarm mode
99  */
100 void systimer_hal_select_alarm_mode(systimer_hal_context_t *hal, uint32_t alarm_id, systimer_alarm_mode_t mode);
101 
102 /**
103  * @brief update systimer step when apb clock gets changed
104  */
105 void systimer_hal_on_apb_freq_update(systimer_hal_context_t *hal, uint32_t apb_ticks_per_us);
106 
107 /**
108  * @brief move systimer counter value forward or backward
109  */
110 void systimer_hal_counter_value_advance(systimer_hal_context_t *hal, uint32_t counter_id, int64_t time_us);
111 
112 /**
113  * @brief  connect alarm unit to selected counter
114  */
115 void systimer_hal_connect_alarm_counter(systimer_hal_context_t *hal, uint32_t alarm_id, uint32_t counter_id);
116 
117 /**
118  * @brief  set if a counter should be stalled when CPU is halted by the debugger
119  */
120 void systimer_hal_counter_can_stall_by_cpu(systimer_hal_context_t *hal, uint32_t counter_id, uint32_t cpu_id, bool can);
121 
122 #if !SOC_SYSTIMER_FIXED_DIVIDER
123 /**
124  * @brief set increase steps for systimer counter on different clock source
125  */
126 void systimer_hal_set_steps_per_tick(systimer_hal_context_t *hal, int clock_source, uint32_t steps);
127 #endif
128 
129 /**
130  * @brief Set Systimer clock source
131  */
132 void systimer_hal_set_clock_source(systimer_hal_context_t *hal, systimer_clock_source_t clk_src);
133 
134 /**
135  * @brief Get Systimer clock source
136  */
137 systimer_clock_source_t systimer_hal_get_clock_source(systimer_hal_context_t *hal);
138 
139 #ifdef __cplusplus
140 }
141 #endif
142