1 /*********************************************************************************************************************** 2 * Copyright [2020-2022] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved. 3 * 4 * This software and documentation are supplied by Renesas Electronics America Inc. and may only be used with products 5 * of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. Renesas products are 6 * sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for the selection and use 7 * of Renesas products and Renesas assumes no liability. No license, express or implied, to any intellectual property 8 * right is granted by Renesas. This software is protected under all applicable laws, including copyright laws. Renesas 9 * reserves the right to change or discontinue this software and/or this documentation. THE SOFTWARE AND DOCUMENTATION 10 * IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND TO THE FULLEST EXTENT 11 * PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, INCLUDING WARRANTIES 12 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE SOFTWARE OR 13 * DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. TO THE MAXIMUM 14 * EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR DOCUMENTATION 15 * (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, INCLUDING, 16 * WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY LOST PROFITS, 17 * OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY 18 * OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS. 19 **********************************************************************************************************************/ 20 21 #ifndef R_TIMER_API_H 22 #define R_TIMER_API_H 23 24 /*******************************************************************************************************************//** 25 * @defgroup TIMER_API Timer Interface 26 * @ingroup RENESAS_INTERFACES 27 * @brief Interface for timer functions. 28 * 29 * @section TIMER_API_SUMMARY Summary 30 * The general timer interface provides standard timer functionality including periodic mode, one-shot mode, PWM output, 31 * and free-running timer mode. After each timer cycle (overflow or underflow), an interrupt can be triggered. 32 * 33 * If an instance supports output compare mode, it is provided in the extension configuration 34 * timer_on_<instance>_cfg_t defined in r_<instance>.h. 35 * 36 * Implemented by: 37 * - @ref GPT 38 * - @ref AGT 39 * 40 * @{ 41 **********************************************************************************************************************/ 42 43 /*********************************************************************************************************************** 44 * Includes 45 **********************************************************************************************************************/ 46 47 /* Includes board and MCU related header files. */ 48 #include "bsp_api.h" 49 50 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 51 FSP_HEADER 52 53 /********************************************************************************************************************** 54 * Macro definitions 55 **********************************************************************************************************************/ 56 57 /* Leading zeroes removed to avoid coding standard violation. */ 58 59 /********************************************************************************************************************** 60 * Typedef definitions 61 **********************************************************************************************************************/ 62 63 /** Events that can trigger a callback function */ 64 typedef enum e_timer_event 65 { 66 TIMER_EVENT_CYCLE_END, ///< Requested timer delay has expired or timer has wrapped around 67 TIMER_EVENT_CREST = TIMER_EVENT_CYCLE_END, ///< Timer crest event (counter is at a maximum, triangle-wave PWM only) 68 TIMER_EVENT_CAPTURE_A, ///< A capture has occurred on signal A 69 TIMER_EVENT_CAPTURE_B, ///< A capture has occurred on signal B 70 TIMER_EVENT_TROUGH, ///< Timer trough event (counter is 0, triangle-wave PWM only 71 } timer_event_t; 72 73 /** Timer variant types. */ 74 typedef enum e_timer_variant 75 { 76 TIMER_VARIANT_32_BIT, ///< 32-bit timer 77 TIMER_VARIANT_16_BIT ///< 16-bit timer 78 } timer_variant_t; 79 80 /** Callback function parameter data */ 81 typedef struct st_timer_callback_args 82 { 83 /** Placeholder for user data. Set in @ref timer_api_t::open function in @ref timer_cfg_t. */ 84 void const * p_context; 85 timer_event_t event; ///< The event can be used to identify what caused the callback. 86 87 /** Most recent capture, only valid if event is TIMER_EVENT_CAPTURE_A or TIMER_EVENT_CAPTURE_B. */ 88 uint32_t capture; 89 } timer_callback_args_t; 90 91 /** Timer control block. Allocate an instance specific control block to pass into the timer API calls. 92 * @par Implemented as 93 * - gpt_instance_ctrl_t 94 * - agt_instance_ctrl_t 95 */ 96 typedef void timer_ctrl_t; 97 98 /** Possible status values returned by @ref timer_api_t::statusGet. */ 99 typedef enum e_timer_state 100 { 101 TIMER_STATE_STOPPED = 0, ///< Timer is stopped 102 TIMER_STATE_COUNTING = 1, ///< Timer is running 103 } timer_state_t; 104 105 /** Timer operational modes */ 106 typedef enum e_timer_mode 107 { 108 TIMER_MODE_PERIODIC, ///< Timer restarts after period elapses. 109 TIMER_MODE_ONE_SHOT, ///< Timer stops after period elapses. 110 TIMER_MODE_PWM, ///< Timer generates saw-wave PWM output. 111 TIMER_MODE_ONE_SHOT_PULSE, ///< Saw-wave one-shot pulse mode (fixed buffer operation). 112 TIMER_MODE_TRIANGLE_WAVE_SYMMETRIC_PWM = 4U, ///< Timer generates symmetric triangle-wave PWM output. 113 TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM = 5U, ///< Timer generates asymmetric triangle-wave PWM output. 114 115 /** 116 * Timer generates Asymmetric Triangle-wave PWM output. In PWM mode 3, the duty cycle does 117 * not need to be updated at each tough/crest interrupt. Instead, the trough and crest duty cycle values can be 118 * set once and only need to be updated when the application needs to change the duty cycle. 119 */ 120 TIMER_MODE_TRIANGLE_WAVE_ASYMMETRIC_PWM_MODE3 = 6U, 121 } timer_mode_t; 122 123 /** Direction of timer count */ 124 typedef enum e_timer_direction 125 { 126 TIMER_DIRECTION_DOWN = 0, ///< Timer count goes up 127 TIMER_DIRECTION_UP = 1 ///< Timer count goes down 128 } timer_direction_t; 129 130 /** PCLK 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_t; 145 146 /** Timer information structure to store various information for a timer resource */ 147 typedef struct st_timer_info 148 { 149 timer_direction_t count_direction; ///< Clock counting direction of the timer. 150 uint32_t clock_frequency; ///< Clock frequency of the timer counter. 151 152 /** Period in raw timer counts. 153 * @note For triangle wave PWM modes, the full period is double this value. 154 */ 155 uint32_t period_counts; 156 } timer_info_t; 157 158 /** Current timer status. */ 159 typedef struct st_timer_status 160 { 161 uint32_t counter; ///< Current counter value 162 timer_state_t state; ///< Current timer state (running or stopped) 163 } timer_status_t; 164 165 /** User configuration structure, used in open function */ 166 typedef struct st_timer_cfg 167 { 168 timer_mode_t mode; ///< Select enumerated value from @ref timer_mode_t 169 170 /* Period in raw timer counts. 171 * @note For triangle wave PWM modes, enter the period of half the triangle wave, or half the desired period. 172 */ 173 uint32_t period_counts; ///< Period in raw timer counts 174 timer_source_div_t source_div; ///< Source clock divider 175 uint32_t duty_cycle_counts; ///< Duty cycle in counts 176 177 /** Select a channel corresponding to the channel number of the hardware. */ 178 uint8_t channel; 179 uint8_t cycle_end_ipl; ///< Cycle end interrupt priority 180 IRQn_Type cycle_end_irq; ///< Cycle end interrupt 181 182 /** Callback provided when a timer ISR occurs. Set to NULL for no CPU interrupt. */ 183 void (* p_callback)(timer_callback_args_t * p_args); 184 185 /** Placeholder for user data. Passed to the user callback in @ref timer_callback_args_t. */ 186 void const * p_context; 187 void const * p_extend; ///< Extension parameter for hardware specific settings. 188 } timer_cfg_t; 189 190 /** Timer API structure. General timer functions implemented at the HAL layer follow this API. */ 191 typedef struct st_timer_api 192 { 193 /** Initial configuration. 194 * @par Implemented as 195 * - @ref R_GPT_Open() 196 * - @ref R_AGT_Open() 197 * 198 * @param[in] p_ctrl Pointer to control block. Must be declared by user. Elements set here. 199 * @param[in] p_cfg Pointer to configuration structure. All elements of this structure must be set by user. 200 */ 201 fsp_err_t (* open)(timer_ctrl_t * const p_ctrl, timer_cfg_t const * const p_cfg); 202 203 /** Start the counter. 204 * @par Implemented as 205 * - @ref R_GPT_Start() 206 * - @ref R_AGT_Start() 207 * 208 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 209 */ 210 fsp_err_t (* start)(timer_ctrl_t * const p_ctrl); 211 212 /** Stop the counter. 213 * @par Implemented as 214 * - @ref R_GPT_Stop() 215 * - @ref R_AGT_Stop() 216 * 217 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 218 */ 219 fsp_err_t (* stop)(timer_ctrl_t * const p_ctrl); 220 221 /** Reset the counter to the initial value. 222 * @par Implemented as 223 * - @ref R_GPT_Reset() 224 * - @ref R_AGT_Reset() 225 * 226 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 227 */ 228 fsp_err_t (* reset)(timer_ctrl_t * const p_ctrl); 229 230 /** Enables input capture. 231 * @par Implemented as 232 * - @ref R_GPT_Enable() 233 * - @ref R_AGT_Enable() 234 * 235 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 236 */ 237 fsp_err_t (* enable)(timer_ctrl_t * const p_ctrl); 238 239 /** Disables input capture. 240 * @par Implemented as 241 * - @ref R_GPT_Disable() 242 * - @ref R_AGT_Disable() 243 * 244 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 245 */ 246 fsp_err_t (* disable)(timer_ctrl_t * const p_ctrl); 247 248 /** Set the time until the timer expires. See implementation for details of period update timing. 249 * 250 * @par Implemented as 251 * - @ref R_GPT_PeriodSet() 252 * - @ref R_AGT_PeriodSet() 253 * 254 * @note Timer expiration may or may not generate a CPU interrupt based on how the timer is configured in 255 * @ref timer_api_t::open. 256 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 257 * @param[in] p_period Time until timer should expire. 258 */ 259 fsp_err_t (* periodSet)(timer_ctrl_t * const p_ctrl, uint32_t const period); 260 261 /** Sets the number of counts for the pin level to be high. If the timer is counting, the updated duty cycle is 262 * reflected after the next timer expiration. 263 * 264 * @par Implemented as 265 * - @ref R_GPT_DutyCycleSet() 266 * - @ref R_AGT_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_AGT_InfoGet() 278 * 279 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 280 * @param[out] p_info Collection of information for this timer. 281 */ 282 fsp_err_t (* infoGet)(timer_ctrl_t * const p_ctrl, timer_info_t * const p_info); 283 284 /** Get the current counter value and timer state and store it in p_status. 285 * @par Implemented as 286 * - @ref R_GPT_StatusGet() 287 * - @ref R_AGT_StatusGet() 288 * 289 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 290 * @param[out] p_status Current status of this timer. 291 */ 292 fsp_err_t (* statusGet)(timer_ctrl_t * const p_ctrl, timer_status_t * const p_status); 293 294 /** Specify callback function and optional context pointer and working memory pointer. 295 * @par Implemented as 296 * - @ref R_GPT_CallbackSet() 297 * - @ref R_AGT_CallbackSet() 298 * 299 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 300 * @param[in] p_callback Callback function to register 301 * @param[in] p_context Pointer to send to callback function 302 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 303 * Callback arguments allocated here are only valid during the callback. 304 */ 305 fsp_err_t (* callbackSet)(timer_ctrl_t * const p_api_ctrl, void (* p_callback)(timer_callback_args_t *), 306 void const * const p_context, timer_callback_args_t * const p_callback_memory); 307 308 /** Allows driver to be reconfigured and may reduce power consumption. 309 * @par Implemented as 310 * - @ref R_GPT_Close() 311 * - @ref R_AGT_Close() 312 * 313 * @param[in] p_ctrl Control block set in @ref timer_api_t::open call for this timer. 314 */ 315 fsp_err_t (* close)(timer_ctrl_t * const p_ctrl); 316 } timer_api_t; 317 318 /** This structure encompasses everything that is needed to use an instance of this interface. */ 319 typedef struct st_timer_instance 320 { 321 timer_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 322 timer_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 323 timer_api_t const * p_api; ///< Pointer to the API structure for this instance 324 } timer_instance_t; 325 326 /*******************************************************************************************************************//** 327 * @} (end defgroup TIMER_API) 328 **********************************************************************************************************************/ 329 330 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 331 FSP_FOOTER 332 333 #endif 334