1 /*********************************************************************************************************************** 2 * Copyright [2015-2017] Renesas Electronics Corporation and/or its licensors. All Rights Reserved. 3 * 4 * This file is part of Renesas SynergyTM Software Package (SSP) 5 * 6 * The contents of this file (the "contents") are proprietary and confidential to Renesas Electronics Corporation 7 * and/or its licensors ("Renesas") and subject to statutory and contractual protections. 8 * 9 * This file is subject to a Renesas SSP license agreement. Unless otherwise agreed in an SSP license agreement with 10 * Renesas: 1) you may not use, copy, modify, distribute, display, or perform the contents; 2) you may not use any name 11 * or mark of Renesas for advertising or publicity purposes or in connection with your use of the contents; 3) RENESAS 12 * MAKES NO WARRANTY OR REPRESENTATIONS ABOUT THE SUITABILITY OF THE CONTENTS FOR ANY PURPOSE; THE CONTENTS ARE PROVIDED 13 * "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 14 * PARTICULAR PURPOSE, AND NON-INFRINGEMENT; AND 4) RENESAS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, OR 15 * CONSEQUENTIAL DAMAGES, INCLUDING DAMAGES RESULTING FROM LOSS OF USE, DATA, OR PROJECTS, WHETHER IN AN ACTION OF 16 * CONTRACT OR TORT, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE CONTENTS. Third-party contents 17 * included in this file may be subject to different terms. 18 **********************************************************************************************************************/ 19 20 /********************************************************************************************************************** 21 * File Name : r_timer_api.h 22 * Description : General timer API. Allows for periodic interrupt creation with a callback function. 23 **********************************************************************************************************************/ 24 25 #ifndef DRV_TIMER_API_H 26 #define DRV_TIMER_API_H 27 28 /*******************************************************************************************************************//** 29 * @ingroup Interface_Library 30 * @defgroup TIMER_API Timer Interface 31 * @brief Interface for timer functions. 32 * 33 * @section TIMER_API_SUMMARY Summary 34 * The general timer interface provides standard timer functionality including periodic mode, one-shot mode, and 35 * free-running timer mode. After each timer cycle (overflow or underflow), an interrupt can be triggered. 36 * 37 * If an instance supports output compare mode, it is provided in the extension configuration 38 * timer_on_<instance>_cfg_t defined in r_<instance>.h. 39 * 40 * Implemented by: 41 * - @ref GPT 42 * - @ref AGT 43 * 44 * See also: 45 * @ref INPUT_CAPTURE_API 46 * 47 * Related SSP architecture topics: 48 * - @ref ssp-interfaces 49 * - @ref ssp-predefined-layers 50 * - @ref using-ssp-modules 51 * 52 * Timer Interface description: @ref HALAGTInterface and @ref HALGPTInterface 53 * @{ 54 **********************************************************************************************************************/ 55 56 /*********************************************************************************************************************** 57 * Includes 58 **********************************************************************************************************************/ 59 /* Includes board and MCU related header files. */ 60 #include "bsp_api.h" 61 62 /* Common macro for SSP header files. There is also a corresponding SSP_FOOTER macro at the end of this file. */ 63 SSP_HEADER 64 65 /********************************************************************************************************************** 66 * Macro definitions 67 **********************************************************************************************************************/ 68 69 /* Leading zeroes removed to avoid coding standard violation. */ 70 #define TIMER_API_VERSION_MAJOR (1U) 71 #define TIMER_API_VERSION_MINOR (5U) 72 73 /********************************************************************************************************************** 74 * Typedef definitions 75 **********************************************************************************************************************/ 76 77 /** Largest supported timer size. Currently up to 32-bit timers are supported. If a 16-bit timer is used, only the 78 * bottom 16 bits of any timer_size_t parameter can be used. Passing in values larger than 16 bits would result in an 79 * error. */ 80 typedef uint32_t timer_size_t; 81 82 /** Events that can trigger a callback function */ 83 typedef enum e_timer_event 84 { 85 TIMER_EVENT_EXPIRED ///< Requested timer delay has expired or timer has wrapped around. 86 } timer_event_t; 87 88 /** Timer variant types. */ 89 typedef enum e_timer_variant 90 { 91 TIMER_VARIANT_32_BIT, ///< 32-bit timer 92 TIMER_VARIANT_16_BIT ///< 16-bit timer 93 } timer_variant_t; 94 95 /** Callback function parameter data */ 96 typedef struct st_timer_callback_args 97 { 98 /** Placeholder for user data. Set in timer_api_t::open function in ::timer_cfg_t. */ 99 void const * p_context; 100 timer_event_t event; ///< The event can be used to identify what caused the callback (overflow or error). 101 } timer_callback_args_t; 102 103 /** Timer control block. Allocate an instance specific control block to pass into the timer API calls. 104 * @par Implemented as 105 * - gpt_instance_ctrl_t 106 * - agt_instance_ctrl_t 107 */ 108 typedef void timer_ctrl_t; 109 110 /** Possible status values returned by timer_api_t::infoGet. */ 111 typedef enum e_timer_status 112 { 113 TIMER_STATUS_COUNTING, ///< Timer is running 114 TIMER_STATUS_STOPPED ///< Timer is stopped 115 } timer_status_t; 116 117 /** Timer operational modes */ 118 typedef enum e_timer_mode 119 { 120 TIMER_MODE_PERIODIC, ///< Timer will restart after delay periods. 121 TIMER_MODE_ONE_SHOT, ///< Timer will stop after delay periods. 122 TIMER_MODE_PWM ///< Timer generate PWM output. 123 } timer_mode_t; 124 125 /** Units of timer period value. */ 126 typedef enum e_timer_unit 127 { 128 TIMER_UNIT_PERIOD_RAW_COUNTS, ///< Period in clock counts 129 TIMER_UNIT_PERIOD_NSEC, ///< Period in nanoseconds 130 TIMER_UNIT_PERIOD_USEC, ///< Period in microseconds 131 TIMER_UNIT_PERIOD_MSEC, ///< Period in milliseconds 132 TIMER_UNIT_PERIOD_SEC, ///< Period in seconds 133 TIMER_UNIT_FREQUENCY_HZ, ///< Frequency in Hz 134 TIMER_UNIT_FREQUENCY_KHZ ///< Frequency in kHz 135 } timer_unit_t; 136 137 /** Units of timer duty cycle value. */ 138 typedef enum e_timer_pwm_unit 139 { 140 TIMER_PWM_UNIT_RAW_COUNTS, ///< Period in clock counts 141 TIMER_PWM_UNIT_PERCENT, ///< Percent unit used for duty cycle 142 TIMER_PWM_UNIT_PERCENT_X_1000, ///< Percent multiplied by 1000 for extra resolution 143 } timer_pwm_unit_t; 144 145 /** Direction of timer count */ 146 typedef enum e_timer_direction 147 { 148 TIMER_DIRECTION_DOWN = 0, ///< Timer count goes up 149 TIMER_DIRECTION_UP = 1 ///< Timer count goes down 150 } timer_direction_t; 151 152 /** DEPRECATED: Recommend using timer_size_t for period. */ 153 typedef timer_size_t timer_period_t; 154 155 /** Timer information structure to store various information for a timer resource */ 156 typedef struct st_timer_info 157 { 158 timer_direction_t count_direction; ///< Clock counting direction of the timer resource. 159 uint32_t clock_frequency; ///< Clock frequency of the timer resource. 160 timer_size_t period_counts; ///< Time in clock counts until timer will expire. 161 timer_status_t status; 162 elc_event_t elc_event; ///< ELC event associated with the count operation of the timer resource. 163 } timer_info_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 ::timer_mode_t 169 170 /** Defines when the timer should expire. For a free running counter, set to TIMER_MAX_CLOCK with unit 171 *::TIMER_UNIT_PERIOD_RAW_COUNTS */ 172 uint32_t period; 173 timer_unit_t unit; ///< Units of timer_cfg_t::period 174 timer_size_t duty_cycle; ///< Duty cycle in units timer_cfg_t::duty_cycle_unit 175 timer_pwm_unit_t duty_cycle_unit; ///< Units of timer_cfg_t::duty_cycle 176 177 /** Select a channel corresponding to the channel number of the hardware. */ 178 uint8_t channel; 179 uint8_t irq_ipl; ///< Timer interrupt priority 180 181 /** Whether to start during Open call or not. True: Start during open. False: Don't start during open. */ 182 bool autostart; 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 ::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 * @par Implemented as 197 * - R_GPT_TimerOpen() 198 * - R_AGT_TimerOpen() 199 * 200 * @note To reconfigure after calling this function, call timer_api_t::close first. 201 * @param[in] p_ctrl Pointer to control block. Must be declared by user. Elements set here. 202 * @param[in] p_cfg Pointer to configuration structure. All elements of this structure must be set by user. 203 */ 204 ssp_err_t (* open)(timer_ctrl_t * const p_ctrl, 205 timer_cfg_t const * const p_cfg); 206 207 /** Stop the counter. 208 * @par Implemented as 209 * - R_GPT_Stop() 210 * - R_AGT_Stop() 211 * 212 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 213 */ 214 ssp_err_t (* stop)(timer_ctrl_t * const p_ctrl); 215 216 /** Start the counter. 217 * @par Implemented as 218 * - R_GPT_Start() 219 * - R_AGT_Start() 220 * 221 * @note The counter can also be started in the timer_api_t::open function if timer_cfg_t::autostart is true. 222 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 223 */ 224 ssp_err_t (* start)(timer_ctrl_t * const p_ctrl); 225 226 /** Reset the counter to the initial value. 227 * @par Implemented as 228 * - R_GPT_Reset() 229 * - R_AGT_Reset() 230 * 231 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 232 */ 233 ssp_err_t (* reset)(timer_ctrl_t * const p_ctrl); 234 235 /** Get current counter value and store it in provided pointer p_value. 236 * @par Implemented as 237 * - R_GPT_CounterGet() 238 * - R_AGT_CounterGet() 239 * 240 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 241 * @param[out] p_value Pointer to store current counter value. 242 */ 243 ssp_err_t (* counterGet)(timer_ctrl_t * const p_ctrl, 244 timer_size_t * const p_value); 245 246 /** Set the time until the timer expires. 247 * @par Implemented as 248 * - R_GPT_PeriodSet() 249 * - R_AGT_PeriodSet() 250 * 251 * @note Timer expiration may or may not generate a CPU interrupt based on how the timer is configured in 252 * timer_api_t::open. 253 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 254 * @param[in] period Time until timer should expire. 255 * @param[in] unit Units of period parameter. 256 */ 257 ssp_err_t (* periodSet)(timer_ctrl_t * const p_ctrl, 258 timer_size_t const period, 259 timer_unit_t const unit); 260 261 /** Sets the time until the duty cycle expires. 262 * 263 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 264 * @param[in] duty_cycle Time until duty cycle should expire. 265 * @param[in] duty_cycle_unit Units of duty_cycle parameter. 266 * @param[in] pin Which output pin to update. Enter the pin number or if pins are identified by 267 * letters, enter 0 for A, 1 for B, 2 for C, etc. 268 */ 269 ssp_err_t (* dutyCycleSet)(timer_ctrl_t * const p_ctrl, 270 timer_size_t const duty_cycle, 271 timer_pwm_unit_t const duty_cycle_unit, 272 uint8_t const pin); 273 274 /** Get the time until the timer expires in clock counts and store it in provided pointer p_period_counts. 275 * @par Implemented as 276 * - R_GPT_InfoGet() 277 * - R_AGT_InfoGet() 278 * 279 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 280 * @param[out] p_info Collection of information for this timer. 281 */ 282 ssp_err_t (* infoGet)(timer_ctrl_t * const p_ctrl, 283 timer_info_t * const p_info); 284 285 /** Allows driver to be reconfigured and may reduce power consumption. 286 * @par Implemented as 287 * - R_GPT_Close() 288 * - R_AGT_Close() 289 * 290 * @param[in] p_ctrl Control block set in timer_api_t::open call for this timer. 291 */ 292 ssp_err_t (* close)(timer_ctrl_t * const p_ctrl); 293 294 /** Get version and store it in provided pointer p_version. 295 * @par Implemented as 296 * - R_GPT_VersionGet() 297 * - R_AGT_VersionGet() 298 * 299 * @param[out] p_version Code and API version used. 300 */ 301 ssp_err_t (* versionGet)(ssp_version_t * const p_version); 302 } timer_api_t; 303 304 /** This structure encompasses everything that is needed to use an instance of this interface. */ 305 typedef struct st_timer_instance 306 { 307 timer_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 308 timer_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 309 timer_api_t const * p_api; ///< Pointer to the API structure for this instance 310 } timer_instance_t; 311 312 313 /*******************************************************************************************************************//** 314 * @} (end defgroup TIMER_API) 315 **********************************************************************************************************************/ 316 317 /* Common macro for SSP header files. There is also a corresponding SSP_HEADER macro at the top of this file. */ 318 SSP_FOOTER 319 320 #endif /* DRV_TIMER_API_H */ 321