1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 21 /** 22 * @addtogroup HAL 23 * @{ 24 * @defgroup HALTimer HAL Timer 25 * @{ 26 */ 27 28 #ifndef H_HAL_TIMER_ 29 #define H_HAL_TIMER_ 30 31 #include <inttypes.h> 32 #include "os/queue.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /* HAL timer callback */ 39 typedef void (*hal_timer_cb)(void *arg); 40 41 /** 42 * The HAL timer structure. The user can declare as many of these structures 43 * as desired. They are enqueued on a particular HW timer queue when the user 44 * calls the :c:func:`hal_timer_start()` or :c:func:`hal_timer_start_at()` API. 45 * The user must have called :c:func:`hal_timer_set_cb()` before starting a 46 * timer. 47 * 48 * NOTE: the user should not have to modify/examine the contents of this 49 * structure; the hal timer API should be used. 50 */ 51 struct hal_timer { 52 /** Internal platform specific pointer */ 53 void *bsp_timer; 54 /** Callback function */ 55 hal_timer_cb cb_func; 56 /** Callback argument */ 57 void *cb_arg; 58 /** Tick at which timer should expire */ 59 uint32_t expiry; 60 TAILQ_ENTRY(hal_timer) link; /* Queue linked list structure */ 61 }; 62 63 /** 64 * Initialize a HW timer. 65 * 66 * @param timer_num The number of the HW timer to initialize 67 * @param cfg Hardware specific timer configuration. This is 68 * passed from BSP directly to the MCU specific driver. 69 */ 70 int hal_timer_init(int timer_num, void *cfg); 71 72 /** 73 * Un-initialize a HW timer. 74 * 75 * @param timer_num The number of the HW timer to un-initialize 76 */ 77 int hal_timer_deinit(int timer_num); 78 79 /** 80 * Config a HW timer at the given frequency and start it. If the exact 81 * frequency is not obtainable the closest obtainable frequency is set. 82 * 83 * @param timer_num The number of the HW timer to configure 84 * @param freq_hz The frequency in Hz to configure the timer at 85 * 86 * @return 0 on success, non-zero error code on failure 87 */ 88 int hal_timer_config(int timer_num, uint32_t freq_hz); 89 90 /** 91 * Returns the resolution of the HW timer. NOTE: the frequency may not be 92 * obtainable so the caller can use this to determine the resolution. 93 * Returns resolution in nanoseconds. A return value of 0 indicates an invalid 94 * timer was used. 95 * 96 * @param timer_num The number of the HW timer to get resolution for 97 * 98 * @return The resolution of the timer 99 */ 100 uint32_t hal_timer_get_resolution(int timer_num); 101 102 /** 103 * Returns the HW timer current tick value 104 * 105 * @param timer_num The HW timer to read the tick value from 106 * 107 * @return The current tick value 108 */ 109 uint32_t hal_timer_read(int timer_num); 110 111 /** 112 * Perform a blocking delay for a number of ticks. 113 * 114 * @param timer_num The timer number to use for the blocking delay 115 * @param ticks The number of ticks to delay for 116 * 117 * @return 0 on success, non-zero error code on failure 118 */ 119 int hal_timer_delay(int timer_num, uint32_t ticks); 120 121 /** 122 * Set the timer structure prior to use. Should not be called if the timer 123 * is running. Must be called at least once prior to using timer. 124 * 125 * @param timer_num The number of the HW timer to configure the callback on 126 * @param tmr The timer structure to use for this timer 127 * @param cb_func The timer callback to call when the timer fires 128 * @param arg An opaque argument to provide the timer callback 129 * 130 * @return 0 on success, non-zero error code on failure. 131 */ 132 int hal_timer_set_cb(int timer_num, struct hal_timer *tmr, hal_timer_cb cb_func, 133 void *arg); 134 135 /** 136 * Start a timer that will expire in 'ticks' ticks. Ticks cannot be 0 137 * 138 * @param tmr The timer to start 139 * @param ticks The number of ticks to expire the timer in 140 * 141 * @return 0 on success, non-zero error code on failure. 142 */ 143 int hal_timer_start(struct hal_timer *tmr, uint32_t ticks); 144 145 /** 146 * Start a timer that will expire when the timer reaches 'tick'. If tick 147 * has already passed the timer callback will be called "immediately" (at 148 * interrupt context). 149 * 150 * @param tmr The timer to start 151 * @param tick The absolute tick value to fire the timer at 152 * 153 * @return 0 on success, non-zero error code on failure. 154 */ 155 int hal_timer_start_at(struct hal_timer *tmr, uint32_t tick); 156 157 /** 158 * Stop a currently running timer; associated callback will NOT be called 159 * 160 * @param tmr The timer to stop 161 */ 162 int hal_timer_stop(struct hal_timer *tmr); 163 164 #ifdef __cplusplus 165 } 166 #endif 167 168 #endif /* H_HAL_TIMER_ */ 169 170 /** 171 * @} HALTimer 172 * @} HAL 173 */ 174