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_TIMERS_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 * 23 * @{ 24 **********************************************************************************************************************/ 25 26 /*********************************************************************************************************************** 27 * Includes 28 **********************************************************************************************************************/ 29 30 /* Includes board and MCU related header files. */ 31 #include "bsp_api.h" 32 33 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 34 FSP_HEADER 35 36 /********************************************************************************************************************** 37 * Macro definitions 38 **********************************************************************************************************************/ 39 40 /********************************************************************************************************************** 41 * Typedef definitions 42 **********************************************************************************************************************/ 43 44 #ifndef BSP_OVERRIDE_TIMER_EVENT_T 45 46 /** Events that can trigger a callback function */ 47 typedef enum e_timer_event 48 { 49 TIMER_EVENT_CYCLE_END, ///< Requested timer delay has expired or timer has wrapped around 50 TIMER_EVENT_CREST = TIMER_EVENT_CYCLE_END, ///< Timer crest event (counter is at a maximum, triangle-wave PWM only) 51 TIMER_EVENT_CAPTURE_A, ///< A capture has occurred on signal A 52 TIMER_EVENT_CAPTURE_B, ///< A capture has occurred on signal B 53 TIMER_EVENT_TROUGH, ///< Timer trough event (counter is 0, triangle-wave PWM only 54 TIMER_EVENT_COMPARE_A, ///< A compare has occurred on signal A 55 TIMER_EVENT_COMPARE_B, ///< A compare has occurred on signal B 56 TIMER_EVENT_COMPARE_C, ///< A compare has occurred on signal C 57 TIMER_EVENT_COMPARE_D, ///< A compare has occurred on signal D 58 TIMER_EVENT_COMPARE_E, ///< A compare has occurred on signal E 59 TIMER_EVENT_COMPARE_F, ///< A compare has occurred on signal F 60 TIMER_EVENT_DEAD_TIME ///< Dead time event 61 } timer_event_t; 62 #endif 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 /** Options for storing compare match value */ 72 typedef enum e_timer_compare_match 73 { 74 TIMER_COMPARE_MATCH_A = 0U, ///< Compare match A value 75 TIMER_COMPARE_MATCH_B = 1U, ///< Compare match B value 76 } timer_compare_match_t; 77 78 /** Callback function parameter data */ 79 typedef struct st_timer_callback_args 80 { 81 /** Placeholder for user data. Set in @ref timer_api_t::open function in @ref timer_cfg_t. */ 82 void const * p_context; 83 timer_event_t event; ///< The event can be used to identify what caused the callback. 84 85 /** Most recent capture, only valid if event is TIMER_EVENT_CAPTURE_A or TIMER_EVENT_CAPTURE_B. */ 86 uint32_t capture; 87 } timer_callback_args_t; 88 89 /** Timer control block. Allocate an instance specific control block to pass into the timer API calls. 90 */ 91 typedef void timer_ctrl_t; 92 93 /** Possible status values returned by @ref timer_api_t::statusGet. */ 94 typedef enum e_timer_state 95 { 96 TIMER_STATE_STOPPED = 0, ///< Timer is stopped 97 TIMER_STATE_COUNTING = 1 ///< Timer is running 98 } timer_state_t; 99 #ifndef BSP_OVERRIDE_TIMER_MODE_T 100 101 /** Timer operational modes */ 102 typedef enum e_timer_mode 103 { 104 TIMER_MODE_PERIODIC, ///< Timer restarts after period elapses. 105 TIMER_MODE_ONE_SHOT, ///< Timer stops after period elapses. 106 TIMER_MODE_PWM, ///< Timer generates saw-wave PWM output. 107 TIMER_MODE_ONE_SHOT_PULSE, ///< Saw-wave one-shot pulse mode (fixed buffer operation). 108 TIMER_MODE_TRIANGLE_WAVE_SYMMETRIC_PWM = 4U, ///< Timer generates symmetric triangle-wave PWM output. 109 TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM = 5U, ///< Timer generates asymmetric triangle-wave PWM output. 110 111 /** 112 * Timer generates Asymmetric Triangle-wave PWM output. In PWM mode 3, the duty cycle does 113 * not need to be updated at each tough/crest interrupt. Instead, the trough and crest duty cycle values can be 114 * set once and only need to be updated when the application needs to change the duty cycle. 115 */ 116 TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM_MODE3 = 6U 117 } timer_mode_t; 118 119 #endif 120 121 /** Direction of timer count */ 122 typedef enum e_timer_direction 123 { 124 TIMER_DIRECTION_DOWN = 0, ///< Timer count goes up 125 TIMER_DIRECTION_UP = 1 ///< Timer count goes down 126 } timer_direction_t; 127 128 #ifndef BSP_OVERRIDE_TIMER_SOURCE_DIV_T 129 130 /** Clock source divisors */ 131 typedef enum e_timer_source_div 132 { 133 TIMER_SOURCE_DIV_1 = 0, ///< Timer clock source divided by 1 134 TIMER_SOURCE_DIV_2 = 1, ///< Timer clock source divided by 2 135 TIMER_SOURCE_DIV_4 = 2, ///< Timer clock source divided by 4 136 TIMER_SOURCE_DIV_8 = 3, ///< Timer clock source divided by 8 137 TIMER_SOURCE_DIV_16 = 4, ///< Timer clock source divided by 16 138 TIMER_SOURCE_DIV_32 = 5, ///< Timer clock source divided by 32 139 TIMER_SOURCE_DIV_64 = 6, ///< Timer clock source divided by 64 140 TIMER_SOURCE_DIV_128 = 7, ///< Timer clock source divided by 128 141 TIMER_SOURCE_DIV_256 = 8, ///< Timer clock source divided by 256 142 TIMER_SOURCE_DIV_512 = 9, ///< Timer clock source divided by 512 143 TIMER_SOURCE_DIV_1024 = 10, ///< Timer clock source divided by 1024 144 TIMER_SOURCE_DIV_8192 = 13, ///< Timer clock source divided by 8192 145 } timer_source_div_t; 146 #endif 147 148 /** Timer information structure to store various information for a timer resource */ 149 typedef struct st_timer_info 150 { 151 timer_direction_t count_direction; ///< Clock counting direction of the timer. 152 uint32_t clock_frequency; ///< Clock frequency of the timer counter. 153 154 /** Period in raw timer counts. 155 * @note For triangle wave PWM modes, the full period is double this value. 156 */ 157 uint32_t period_counts; 158 } timer_info_t; 159 160 /** Current timer status. */ 161 typedef struct st_timer_status 162 { 163 uint32_t counter; ///< Current counter value 164 timer_state_t state; ///< Current timer state (running or stopped) 165 } timer_status_t; 166 167 /** User configuration structure, used in open function */ 168 typedef struct st_timer_cfg 169 { 170 timer_mode_t mode; ///< Select enumerated value from @ref timer_mode_t 171 172 /* Period in raw timer counts. 173 * @note For triangle wave PWM modes, enter the period of half the triangle wave, or half the desired period. 174 */ 175 uint32_t period_counts; ///< Period in raw timer counts 176 timer_source_div_t source_div; ///< Source clock divider 177 uint32_t duty_cycle_counts; ///< Duty cycle in counts 178 179 /** Select a channel corresponding to the channel number of the hardware. */ 180 uint8_t channel; 181 uint8_t cycle_end_ipl; ///< Cycle end interrupt priority 182 IRQn_Type cycle_end_irq; ///< Cycle end interrupt 183 184 /** Callback provided when a timer ISR occurs. Set to NULL for no CPU interrupt. */ 185 void (* p_callback)(timer_callback_args_t * p_args); 186 187 /** Placeholder for user data. Passed to the user callback in @ref timer_callback_args_t. */ 188 void const * p_context; 189 void const * p_extend; ///< Extension parameter for hardware specific settings. 190 } timer_cfg_t; 191 192 /** Timer API structure. General timer functions implemented at the HAL layer follow this API. */ 193 typedef struct st_timer_api 194 { 195 /** Initial configuration. 196 * 197 * @param[in] p_ctrl Pointer to control block. Must be declared by user. Elements set here. 198 * @param[in] p_cfg Pointer to configuration structure. All elements of this structure must be set by user. 199 */ 200 fsp_err_t (* open)(timer_ctrl_t * const p_ctrl, timer_cfg_t const * const p_cfg); 201 202 /** Start the counter. 203 * 204 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 205 */ 206 fsp_err_t (* start)(timer_ctrl_t * const p_ctrl); 207 208 /** Stop the counter. 209 * 210 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 211 */ 212 fsp_err_t (* stop)(timer_ctrl_t * const p_ctrl); 213 214 /** Reset the counter to the initial value. 215 * 216 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 217 */ 218 fsp_err_t (* reset)(timer_ctrl_t * const p_ctrl); 219 220 /** Enables input capture. 221 * 222 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 223 */ 224 fsp_err_t (* enable)(timer_ctrl_t * const p_ctrl); 225 226 /** Disables input capture. 227 * 228 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 229 */ 230 fsp_err_t (* disable)(timer_ctrl_t * const p_ctrl); 231 232 /** Set the time until the timer expires. See implementation for details of period update timing. 233 * 234 * 235 * @note Timer expiration may or may not generate a CPU interrupt based on how the timer is configured in 236 * @ref timer_api_t::open. 237 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 238 * @param[in] period Time until timer should expire. 239 */ 240 fsp_err_t (* periodSet)(timer_ctrl_t * const p_ctrl, uint32_t const period); 241 242 /** Sets the number of counts for the pin level to be high. If the timer is counting, the updated duty cycle is 243 * reflected after the next timer expiration. 244 * 245 * 246 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 247 * @param[in] duty_cycle_counts Time until duty cycle should expire. 248 * @param[in] pin Which output pin to update. See implementation for details. 249 */ 250 fsp_err_t (* dutyCycleSet)(timer_ctrl_t * const p_ctrl, uint32_t const duty_cycle_counts, uint32_t const pin); 251 252 /** Set a compare match value in raw counts. 253 * 254 * 255 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 256 * @param[in] compare_match_value Timer value to trigger a compare match event. 257 * @param[in] match_channel Which channel to update. 258 */ 259 fsp_err_t (* compareMatchSet)(timer_ctrl_t * const p_ctrl, uint32_t const compare_match_value, 260 timer_compare_match_t const match_channel); 261 262 /** Stores timer information in p_info. 263 * 264 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 265 * @param[out] p_info Collection of information for this timer. 266 */ 267 fsp_err_t (* infoGet)(timer_ctrl_t * const p_ctrl, timer_info_t * const p_info); 268 269 /** Get the current counter value and timer state and store it in p_status. 270 * 271 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 272 * @param[out] p_status Current status of this timer. 273 */ 274 fsp_err_t (* statusGet)(timer_ctrl_t * const p_ctrl, timer_status_t * const p_status); 275 276 /** Specify callback function and optional context pointer and working memory pointer. 277 * 278 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 279 * @param[in] p_callback Callback function to register 280 * @param[in] p_context Pointer to send to callback function 281 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 282 * Callback arguments allocated here are only valid during the callback. 283 */ 284 fsp_err_t (* callbackSet)(timer_ctrl_t * const p_ctrl, void (* p_callback)(timer_callback_args_t *), 285 void const * const p_context, timer_callback_args_t * const p_callback_memory); 286 287 /** Allows driver to be reconfigured and may reduce power consumption. 288 * 289 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 290 */ 291 fsp_err_t (* close)(timer_ctrl_t * const p_ctrl); 292 } timer_api_t; 293 294 /** This structure encompasses everything that is needed to use an instance of this interface. */ 295 typedef struct st_timer_instance 296 { 297 timer_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 298 timer_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 299 timer_api_t const * p_api; ///< Pointer to the API structure for this instance 300 } timer_instance_t; 301 302 /*******************************************************************************************************************//** 303 * @} (end defgroup TIMER_API) 304 **********************************************************************************************************************/ 305 306 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 307 FSP_FOOTER 308 309 #endif 310
