1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef R_TIMER_API_H 8 #define R_TIMER_API_H 9 10 /*******************************************************************************************************************//** 11 * @defgroup TIMER_API Timer Interface 12 * @ingroup RENESAS_INTERFACES 13 * @brief Interface for timer functions. 14 * 15 * @section TIMER_API_SUMMARY Summary 16 * The general timer interface provides standard timer functionality including periodic mode, one-shot mode, PWM output, 17 * and free-running timer mode. After each timer cycle (overflow or underflow), an interrupt can be triggered. 18 * 19 * If an instance supports output compare mode, it is provided in the extension configuration 20 * timer_on_<instance>_cfg_t defined in r_<instance>.h. 21 * 22 * Implemented by: 23 * - @ref GPT 24 * - @ref GTM 25 * - @ref MTU3 26 * 27 * @{ 28 **********************************************************************************************************************/ 29 30 /*********************************************************************************************************************** 31 * Includes 32 **********************************************************************************************************************/ 33 34 /* Includes board and MCU related header files. */ 35 #include "bsp_api.h" 36 37 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 38 FSP_HEADER 39 40 /********************************************************************************************************************** 41 * Macro definitions 42 **********************************************************************************************************************/ 43 44 /********************************************************************************************************************** 45 * Typedef definitions 46 **********************************************************************************************************************/ 47 48 /** Events that can trigger a callback function */ 49 typedef enum e_timer_event 50 { 51 TIMER_EVENT_CYCLE_END, ///< Requested timer delay has expired or timer has wrapped around 52 TIMER_EVENT_CREST = TIMER_EVENT_CYCLE_END, ///< Timer crest event (counter is at a maximum, triangle-wave PWM only) 53 TIMER_EVENT_CAPTURE_A, ///< A capture has occurred on signal A 54 TIMER_EVENT_CAPTURE_B, ///< A capture has occurred on signal B 55 TIMER_EVENT_TROUGH, ///< Timer trough event (counter is 0, triangle-wave PWM only 56 TIMER_EVENT_OUTPUT_COMPARE_0, ///< An output has occurred on signal 0 57 TIMER_EVENT_OUTPUT_COMPARE_1, ///< An output has occurred on signal 1 58 TIMER_EVENT_DEAD_TIME, ///< Dead time event 59 TIMER_EVENT_CAPTURE_U, ///< A capture has occurred on signal U 60 TIMER_EVENT_CAPTURE_V, ///< A capture has occurred on signal V 61 TIMER_EVENT_CAPTURE_W, ///< A capture has occurred on signal W 62 } timer_event_t; 63 64 /** Timer variant types. */ 65 typedef enum e_timer_variant 66 { 67 TIMER_VARIANT_32_BIT, ///< 32-bit timer 68 TIMER_VARIANT_16_BIT ///< 16-bit timer 69 } timer_variant_t; 70 71 /** Callback function parameter data */ 72 typedef struct st_timer_callback_args 73 { 74 /** Placeholder for user data. Set in @ref timer_api_t::open function in @ref timer_cfg_t. */ 75 void const * p_context; 76 timer_event_t event; ///< The event can be used to identify what caused the callback. 77 78 /** Most recent capture, only valid if event is TIMER_EVENT_CAPTURE_A or TIMER_EVENT_CAPTURE_B. */ 79 uint32_t capture; 80 } timer_callback_args_t; 81 82 /** Timer control block. Allocate an instance specific control block to pass into the timer API calls. 83 * @par Implemented as 84 * - gpt_instance_ctrl_t 85 * - gtm_instance_ctrl_t 86 * - mtu3_instance_ctrl_t 87 */ 88 typedef void timer_ctrl_t; 89 90 /** Possible status values returned by @ref timer_api_t::statusGet. */ 91 typedef enum e_timer_state 92 { 93 TIMER_STATE_STOPPED = 0, ///< Timer is stopped 94 TIMER_STATE_COUNTING = 1, ///< Timer is running 95 } timer_state_t; 96 97 /** Timer operational modes */ 98 typedef enum e_timer_mode 99 { 100 TIMER_MODE_PERIODIC, ///< Timer restarts after period elapses. 101 TIMER_MODE_ONE_SHOT, ///< Timer stops after period elapses. 102 TIMER_MODE_PWM, ///< Timer generates saw-wave PWM output. 103 TIMER_MODE_ONE_SHOT_PULSE, ///< Saw-wave one-shot pulse mode (fixed buffer operation). 104 TIMER_MODE_TRIANGLE_WAVE_SYMMETRIC_PWM = 4U, ///< Timer generates symmetric triangle-wave PWM output. 105 TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM = 5U, ///< Timer generates asymmetric triangle-wave PWM output. 106 107 /** 108 * Timer generates Asymmetric Triangle-wave PWM output. In PWM mode 3, the duty cycle does 109 * not need to be updated at each tough/crest interrupt. Instead, the trough and crest duty cycle values can be 110 * set once and only need to be updated when the application needs to change the duty cycle. 111 */ 112 TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM_MODE3 = 6U, 113 } timer_mode_t; 114 115 /** Direction of timer count */ 116 typedef enum e_timer_direction 117 { 118 TIMER_DIRECTION_DOWN = 0, ///< Timer count goes up 119 TIMER_DIRECTION_UP = 1 ///< Timer count goes down 120 } timer_direction_t; 121 122 /** Clock source divisors */ 123 typedef enum e_timer_source_div 124 { 125 TIMER_SOURCE_DIV_1 = 0, ///< Timer clock source divided by 1 126 TIMER_SOURCE_DIV_2 = 1, ///< Timer clock source divided by 2 127 TIMER_SOURCE_DIV_4 = 2, ///< Timer clock source divided by 4 128 TIMER_SOURCE_DIV_8 = 3, ///< Timer clock source divided by 8 129 TIMER_SOURCE_DIV_16 = 4, ///< Timer clock source divided by 16 130 TIMER_SOURCE_DIV_32 = 5, ///< Timer clock source divided by 32 131 TIMER_SOURCE_DIV_64 = 6, ///< Timer clock source divided by 64 132 TIMER_SOURCE_DIV_128 = 7, ///< Timer clock source divided by 128 133 TIMER_SOURCE_DIV_256 = 8, ///< Timer clock source divided by 256 134 TIMER_SOURCE_DIV_512 = 9, ///< Timer clock source divided by 512 135 TIMER_SOURCE_DIV_1024 = 10, ///< Timer clock source divided by 1024 136 } timer_source_div_t; 137 138 /** Timer information structure to store various information for a timer resource */ 139 typedef struct st_timer_info 140 { 141 timer_direction_t count_direction; ///< Clock counting direction of the timer. 142 uint32_t clock_frequency; ///< Clock frequency of the timer counter. 143 144 /** Period in raw timer counts. 145 * @note For triangle wave PWM modes, the full period is double this value. 146 */ 147 uint32_t period_counts; 148 } timer_info_t; 149 150 /** Current timer status. */ 151 typedef struct st_timer_status 152 { 153 uint32_t counter; ///< Current counter value 154 timer_state_t state; ///< Current timer state (running or stopped) 155 } timer_status_t; 156 157 /** User configuration structure, used in open function */ 158 typedef struct st_timer_cfg 159 { 160 timer_mode_t mode; ///< Select enumerated value from @ref timer_mode_t 161 162 /* Period in raw timer counts. 163 * @note For triangle wave PWM modes, enter the period of half the triangle wave, or half the desired period. 164 */ 165 uint32_t period_counts; ///< Period in raw timer counts 166 timer_source_div_t source_div; ///< Source clock divider 167 uint32_t duty_cycle_counts; ///< Duty cycle in counts 168 169 /** Select a channel corresponding to the channel number of the hardware. */ 170 uint8_t channel; 171 uint8_t cycle_end_ipl; ///< Cycle end interrupt priority 172 IRQn_Type cycle_end_irq; ///< Cycle end interrupt 173 174 /** Callback provided when a timer ISR occurs. Set to NULL for no CPU interrupt. */ 175 void (* p_callback)(timer_callback_args_t * p_args); 176 177 /** Placeholder for user data. Passed to the user callback in @ref timer_callback_args_t. */ 178 void const * p_context; 179 void const * p_extend; ///< Extension parameter for hardware specific settings. 180 } timer_cfg_t; 181 182 /** Timer API structure. General timer functions implemented at the HAL layer follow this API. */ 183 typedef struct st_timer_api 184 { 185 /** Initial configuration. 186 * @par Implemented as 187 * - @ref R_GPT_Open() 188 * - @ref R_GTM_Open() 189 * - @ref R_MTU3_Open() 190 * 191 * @param[in] p_ctrl Pointer to control block. Must be declared by user. Elements set here. 192 * @param[in] p_cfg Pointer to configuration structure. All elements of this structure must be set by user. 193 */ 194 fsp_err_t (* open)(timer_ctrl_t * const p_ctrl, timer_cfg_t const * const p_cfg); 195 196 /** Start the counter. 197 * @par Implemented as 198 * - @ref R_GPT_Start() 199 * - @ref R_GTM_Start() 200 * - @ref R_MTU3_Start() 201 * 202 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 203 */ 204 fsp_err_t (* start)(timer_ctrl_t * const p_ctrl); 205 206 /** Stop the counter. 207 * @par Implemented as 208 * - @ref R_GPT_Stop() 209 * - @ref R_GTM_Stop() 210 * - @ref R_MTU3_Stop() 211 * 212 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 213 */ 214 fsp_err_t (* stop)(timer_ctrl_t * const p_ctrl); 215 216 /** Reset the counter to the initial value. 217 * @par Implemented as 218 * - @ref R_GPT_Reset() 219 * - @ref R_GTM_Reset() 220 * - @ref R_MTU3_Reset() 221 * 222 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 223 */ 224 fsp_err_t (* reset)(timer_ctrl_t * const p_ctrl); 225 226 /** Enables input capture. 227 * @par Implemented as 228 * - @ref R_GPT_Enable() 229 * - @ref R_GTM_Enable() 230 * - @ref R_MTU3_Enable() 231 * 232 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 233 */ 234 fsp_err_t (* enable)(timer_ctrl_t * const p_ctrl); 235 236 /** Disables input capture. 237 * @par Implemented as 238 * - @ref R_GPT_Disable() 239 * - @ref R_GTM_Disable() 240 * - @ref R_MTU3_Disable() 241 * 242 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 243 */ 244 fsp_err_t (* disable)(timer_ctrl_t * const p_ctrl); 245 246 /** Set the time until the timer expires. See implementation for details of period update timing. 247 * 248 * @par Implemented as 249 * - @ref R_GPT_PeriodSet() 250 * - @ref R_GTM_PeriodSet() 251 * - @ref R_MTU3_PeriodSet() 252 * 253 * @note Timer expiration may or may not generate a CPU interrupt based on how the timer is configured in 254 * @ref timer_api_t::open. 255 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 256 * @param[in] p_period Time until timer should expire. 257 */ 258 fsp_err_t (* periodSet)(timer_ctrl_t * const p_ctrl, uint32_t const period); 259 260 /** Sets the number of counts for the pin level to be high. If the timer is counting, the updated duty cycle is 261 * reflected after the next timer expiration. 262 * 263 * @par Implemented as 264 * - @ref R_GPT_DutyCycleSet() 265 * - @ref R_GTM_DutyCycleSet() 266 * - @ref R_MTU3_DutyCycleSet() 267 * 268 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 269 * @param[in] duty_cycle_counts Time until duty cycle should expire. 270 * @param[in] pin Which output pin to update. See implementation for details. 271 */ 272 fsp_err_t (* dutyCycleSet)(timer_ctrl_t * const p_ctrl, uint32_t const duty_cycle_counts, uint32_t const pin); 273 274 /** Stores timer information in p_info. 275 * @par Implemented as 276 * - @ref R_GPT_InfoGet() 277 * - @ref R_GTM_InfoGet() 278 * - @ref R_MTU3_InfoGet() 279 * 280 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 281 * @param[out] p_info Collection of information for this timer. 282 */ 283 fsp_err_t (* infoGet)(timer_ctrl_t * const p_ctrl, timer_info_t * const p_info); 284 285 /** Get the current counter value and timer state and store it in p_status. 286 * @par Implemented as 287 * - @ref R_GPT_StatusGet() 288 * - @ref R_GTM_StatusGet() 289 * - @ref R_MTU3_StatusGet() 290 * 291 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 292 * @param[out] p_status Current status of this timer. 293 */ 294 fsp_err_t (* statusGet)(timer_ctrl_t * const p_ctrl, timer_status_t * const p_status); 295 296 /** Specify callback function and optional context pointer and working memory pointer. 297 * @par Implemented as 298 * - @ref R_GPT_CallbackSet() 299 * - @ref R_GTM_CallbackSet() 300 * - @ref R_MTU3_CallbackSet() 301 * 302 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 303 * @param[in] p_callback Callback function to register 304 * @param[in] p_context Pointer to send to callback function 305 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 306 * Callback arguments allocated here are only valid during the callback. 307 */ 308 fsp_err_t (* callbackSet)(timer_ctrl_t * const p_api_ctrl, void (* p_callback)(timer_callback_args_t *), 309 void const * const p_context, timer_callback_args_t * const p_callback_memory); 310 311 /** Allows driver to be reconfigured and may reduce power consumption. 312 * @par Implemented as 313 * - @ref R_GPT_Close() 314 * - @ref R_GTM_Close() 315 * - @ref R_MTU3_Close() 316 * 317 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 318 */ 319 fsp_err_t (* close)(timer_ctrl_t * const p_ctrl); 320 } timer_api_t; 321 322 /** This structure encompasses everything that is needed to use an instance of this interface. */ 323 typedef struct st_timer_instance 324 { 325 timer_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 326 timer_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 327 timer_api_t const * p_api; ///< Pointer to the API structure for this instance 328 } timer_instance_t; 329 330 /*******************************************************************************************************************//** 331 * @} (end defgroup TIMER_API) 332 **********************************************************************************************************************/ 333 334 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 335 FSP_FOOTER 336 337 #endif 338
