1 /*! 2 * \file timer.h 3 * 4 * \brief Timer objects and scheduling management implementation 5 * 6 * \copyright Revised BSD License, see section \ref LICENSE. 7 * 8 * \code 9 * ______ _ 10 * / _____) _ | | 11 * ( (____ _____ ____ _| |_ _____ ____| |__ 12 * \____ \| ___ | (_ _) ___ |/ ___) _ \ 13 * _____) ) ____| | | || |_| ____( (___| | | | 14 * (______/|_____)_|_|_| \__)_____)\____)_| |_| 15 * (C)2013-2017 Semtech 16 * 17 * \endcode 18 * 19 * \author Miguel Luis ( Semtech ) 20 * 21 * \author Gregory Cristian ( Semtech ) 22 */ 23 24 /****************************************************************************** 25 * @file stm32_timer.h 26 * @author MCD Application Team 27 * @brief This is the header of the timer server driver 28 ****************************************************************************** 29 * @attention 30 * 31 * <h2><center>© Copyright (c) 2019 STMicroelectronics. 32 * All rights reserved.</center></h2> 33 * 34 * This software is licensed under terms that can be found in the LICENSE file 35 * in the root directory of this software component. 36 * If no LICENSE file comes with this software, it is provided AS-IS. 37 * 38 ****************************************************************************** 39 */ 40 41 /* Define to prevent recursive inclusion -------------------------------------*/ 42 #ifndef UTIL_TIME_SERVER_H__ 43 #define UTIL_TIME_SERVER_H__ 44 45 #ifdef __cplusplus 46 47 extern "C" { 48 #endif 49 50 /** @defgroup TIMER_SERVER timer server 51 * @{ 52 */ 53 54 /* Includes ------------------------------------------------------------------*/ 55 #include <stdbool.h> 56 #include <stdint.h> 57 #include <stddef.h> 58 #include <cmsis_compiler.h> 59 #include "utilities_conf.h" 60 61 /* Exported types ------------------------------------------------------------*/ 62 /** @defgroup TIMER_SERVER_exported_TypeDef TIMER_SERVER exported Typedef 63 * @{ 64 */ 65 66 /** 67 * @brief Timer mode 68 */ 69 typedef enum { 70 UTIL_TIMER_ONESHOT = 0, /*!<One-shot timer. */ 71 UTIL_TIMER_PERIODIC = 1 /*!<Periodic timer. */ 72 } UTIL_TIMER_Mode_t; 73 74 75 /** 76 * @brief Timer status 77 */ 78 typedef enum { 79 UTIL_TIMER_OK = 0, /*!<Operation terminated successfully.*/ 80 UTIL_TIMER_INVALID_PARAM = 1, /*!<Invalid Parameter. */ 81 UTIL_TIMER_HW_ERROR = 2, /*!<Hardware Error. */ 82 UTIL_TIMER_UNKNOWN_ERROR = 3 /*!<Unknown Error. */ 83 } UTIL_TIMER_Status_t; 84 85 /** 86 * @brief Timer object description 87 */ 88 typedef struct TimerEvent_s 89 { 90 uint32_t Timestamp; /*!<Expiring timer value in ticks from TimerContext */ 91 uint32_t ReloadValue; /*!<Reload Value when Timer is restarted */ 92 uint8_t IsPending; /*!<Is the timer waiting for an event */ 93 uint8_t IsRunning; /*!<Is the timer running */ 94 uint8_t IsReloadStopped; /*!<Is the reload stopped */ 95 UTIL_TIMER_Mode_t Mode; /*!<Timer type : one-shot/continuous */ 96 void ( *Callback )( void *); /*!<callback function */ 97 void *argument; /*!<callback argument */ 98 struct TimerEvent_s *Next; /*!<Pointer to the next Timer object. */ 99 } UTIL_TIMER_Object_t; 100 101 /** 102 * @brief Timer driver definition 103 */ 104 typedef struct 105 { 106 UTIL_TIMER_Status_t (* InitTimer )( void ); /*!< Initialisation of the low layer timer */ 107 UTIL_TIMER_Status_t (* DeInitTimer )( void ); /*!< Un-Initialisation of the low layer timer */ 108 109 UTIL_TIMER_Status_t (* StartTimerEvt )( uint32_t timeout ); /*!< Start the low layer timer */ 110 UTIL_TIMER_Status_t (* StopTimerEvt )( void); /*!< Stop the low layer timer */ 111 112 uint32_t (* SetTimerContext)( void ); /*!< Set the timer context */ 113 uint32_t (* GetTimerContext)( void ); /*!< Get the timer context */ 114 115 uint32_t (* GetTimerElapsedTime)( void ); /*!< Get elapsed time */ 116 uint32_t (* GetTimerValue)( void ); /*!< Get timer value */ 117 uint32_t (* GetMinimumTimeout)( void ); /*!< Get Minimum timeout */ 118 119 uint32_t (* ms2Tick)( uint32_t timeMicroSec ); /*!< convert ms to tick */ 120 uint32_t (* Tick2ms)( uint32_t tick ); /*!< convert tick into ms */ 121 } UTIL_TIMER_Driver_s; 122 123 /** 124 * @brief Timer value on 32 bits 125 */ 126 typedef uint32_t UTIL_TIMER_Time_t; 127 /** 128 * @} 129 */ 130 131 /* Exported variables ------------------------------------------------------------*/ 132 /** @defgroup TIMER_SERVER_exported_Variable TIMER_SERVER exported Variable 133 * @{ 134 */ 135 /** 136 * @brief low layer interface to handle timing execution 137 * 138 * @remark This structure is defined and initialized in the specific platform 139 * timer implementation 140 */ 141 extern const UTIL_TIMER_Driver_s UTIL_TimerDriver; 142 143 /** 144 * @} 145 */ 146 147 /* Exported constants --------------------------------------------------------*/ 148 /* External variables --------------------------------------------------------*/ 149 /* Exported macros -----------------------------------------------------------*/ 150 /* Exported functions ------------------------------------------------------- */ 151 152 /** @defgroup TIMER_SERVER_exported_function TIMER_SERVER exported function 153 * @{ 154 */ 155 156 /** 157 * @brief Initialize the timer server 158 * 159 * @retval Status based on @ref UTIL_TIMER_Status_t 160 */ 161 UTIL_TIMER_Status_t UTIL_TIMER_Init(void); 162 163 /** 164 * @brief Un-Initialize the timer server 165 * 166 * @retval Status based on @ref UTIL_TIMER_Status_t 167 */ 168 UTIL_TIMER_Status_t UTIL_TIMER_DeInit(void); 169 170 /** 171 * @brief Create the timer object 172 * 173 * @remark TimerSetValue function must be called before starting the timer. 174 * this function initializes timestamp and reload value at 0. 175 * 176 * @param TimerObject Structure containing the timer object parameters 177 * @param PeriodValue Period value of the timer in ms 178 * @param Mode @ref UTIL_TIMER_Mode_t 179 * @param Callback Function callback called at the end of the timeout 180 * @param Argument argument for the callback function 181 * @retval Status based on @ref UTIL_TIMER_Status_t 182 */ 183 UTIL_TIMER_Status_t UTIL_TIMER_Create( UTIL_TIMER_Object_t *TimerObject, uint32_t PeriodValue, UTIL_TIMER_Mode_t Mode, void ( *Callback )( void *) , void *Argument); 184 185 /** 186 * @brief Start and adds the timer object to the list of timer events 187 * 188 * @param TimerObject Structure containing the timer object parameters 189 * @retval Status based on @ref UTIL_TIMER_Status_t 190 */ 191 UTIL_TIMER_Status_t UTIL_TIMER_Start( UTIL_TIMER_Object_t *TimerObject ); 192 193 /** 194 * @brief Start and adds the timer object to the list of timer events 195 * 196 * @param TimerObject Structure containing the timer object parameters 197 * @param PeriodValue period value of the timer 198 * @retval Status based on @ref UTIL_TIMER_Status_t 199 */ 200 UTIL_TIMER_Status_t UTIL_TIMER_StartWithPeriod( UTIL_TIMER_Object_t *TimerObject, uint32_t PeriodValue); 201 202 /** 203 * @brief Stop and removes the timer object from the list of timer events 204 * 205 * @param TimerObject Structure containing the timer object parameters 206 * @retval Status based on @ref UTIL_TIMER_Status_t 207 */ 208 UTIL_TIMER_Status_t UTIL_TIMER_Stop( UTIL_TIMER_Object_t *TimerObject ); 209 210 211 /** 212 * @brief update the period and start the timer 213 * 214 * @param TimerObject Structure containing the timer object parameters 215 * @param NewPeriodValue new period value of the timer 216 * @retval Status based on @ref UTIL_TIMER_Status_t 217 */ 218 UTIL_TIMER_Status_t UTIL_TIMER_SetPeriod(UTIL_TIMER_Object_t *TimerObject, uint32_t NewPeriodValue); 219 220 /** 221 * @brief update the period and start the timer 222 * 223 * @param TimerObject Structure containing the timer object parameters 224 * @param ReloadMode new reload mode @ref UTIL_TIMER_Mode_t 225 * @retval Status based on @ref UTIL_TIMER_Status_t 226 */ 227 UTIL_TIMER_Status_t UTIL_TIMER_SetReloadMode(UTIL_TIMER_Object_t *TimerObject, UTIL_TIMER_Mode_t ReloadMode); 228 229 /** 230 * @brief get the remaining time before timer expiration 231 * * 232 * @param TimerObject Structure containing the timer object parameters 233 * @param Time time before expiration in ms 234 * @retval Status based on @ref UTIL_TIMER_Status_t 235 */ 236 UTIL_TIMER_Status_t UTIL_TIMER_GetRemainingTime(UTIL_TIMER_Object_t *TimerObject, uint32_t *Time); 237 238 /** 239 * @brief return timer state 240 * 241 * @param TimerObject Structure containing the timer object parameters 242 * @retval boolean value is returned 0 = false and 1 = true 243 */ 244 uint32_t UTIL_TIMER_IsRunning( UTIL_TIMER_Object_t *TimerObject ); 245 246 247 /** 248 * @brief return the remaining time of the first timer in the chain list 249 * 250 * @retval return the time in ms, the value 0xFFFFFFFF means no timer running 251 */ 252 uint32_t UTIL_TIMER_GetFirstRemainingTime(void); 253 254 /** 255 * @brief return the current time 256 * 257 * @retval time value 258 */ 259 UTIL_TIMER_Time_t UTIL_TIMER_GetCurrentTime(void); 260 261 262 /** 263 * @brief return the elapsed time 264 * 265 * @param past a value returned by the function UTIL_TIMER_GetCurrentTime 266 * @retval elapsed time value 267 */ 268 UTIL_TIMER_Time_t UTIL_TIMER_GetElapsedTime(UTIL_TIMER_Time_t past ); 269 270 /** 271 * @brief return the list of the current timer 272 * 273 * @retval pointer on @ref UTIL_TIMER_Object_t 274 * 275 * @Note : the use of this function is dangerous and must be done with precaution, the risks are: 276 * 1 - an update of this data structure may affect the operation of timer server 277 * 2 - data structure is moving according the events, so read must be under critical section 278 */ 279 UTIL_TIMER_Object_t *UTIL_TIMER_GetTimerList(void); 280 281 /** 282 * @brief Timer IRQ event handler 283 * 284 * @note Head Timer Object is automatically removed from the List 285 * 286 * @note e.g. it is not needed to stop it 287 */ 288 void UTIL_TIMER_IRQ_Handler( void ); 289 290 /** 291 * @} 292 */ 293 294 /** 295 * @} 296 */ 297 298 #ifdef __cplusplus 299 } 300 #endif 301 302 #endif /* UTIL_TIME_SERVER_H__*/ 303
