1 /** 2 * @file tmr.h 3 * @brief Timer (TMR) function prototypes and data types. 4 */ 5 6 /* **************************************************************************** 7 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved. 8 * 9 * Permission is hereby granted, free of charge, to any person obtaining a 10 * copy of this software and associated documentation files (the "Software"), 11 * to deal in the Software without restriction, including without limitation 12 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 13 * and/or sell copies of the Software, and to permit persons to whom the 14 * Software is furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be included 17 * in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 20 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 22 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES 23 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 24 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 25 * OTHER DEALINGS IN THE SOFTWARE. 26 * 27 * Except as contained in this notice, the name of Maxim Integrated 28 * Products, Inc. shall not be used except as stated in the Maxim Integrated 29 * Products, Inc. Branding Policy. 30 * 31 * The mere transfer of this software does not imply any licenses 32 * of trade secrets, proprietary technology, copyrights, patents, 33 * trademarks, maskwork rights, or any other form of intellectual 34 * property whatsoever. Maxim Integrated Products, Inc. retains all 35 * ownership rights. 36 * 37 * $Date: 2019-09-11 14:32:22 -0500 (Wed, 11 Sep 2019) $ 38 * $Revision: 46047 $ 39 * 40 *************************************************************************** */ 41 42 /* Define to prevent redundant inclusion */ 43 #ifndef _TMR_H_ 44 #define _TMR_H_ 45 46 /* **** Includes **** */ 47 #include "mxc_config.h" 48 #include "tmr_regs.h" 49 #include "mxc_sys.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @defgroup tmr Timer (TMR) 57 * @ingroup periphlibs 58 * @{ 59 */ 60 61 /** 62 * @brief Timer prescaler values 63 */ 64 typedef enum { 65 TMR_PRES_1 = MXC_S_TMR_CN_PRES_DIV1, /// Divide input clock by 1 66 TMR_PRES_2 = MXC_S_TMR_CN_PRES_DIV2, /// Divide input clock by 2 67 TMR_PRES_4 = MXC_S_TMR_CN_PRES_DIV4, /// Divide input clock by 4 68 TMR_PRES_8 = MXC_S_TMR_CN_PRES_DIV8, /// Divide input clock by 8 69 TMR_PRES_16 = MXC_S_TMR_CN_PRES_DIV16, /// Divide input clock by 16 70 TMR_PRES_32 = MXC_S_TMR_CN_PRES_DIV32, /// Divide input clock by 32 71 TMR_PRES_64 = MXC_S_TMR_CN_PRES_DIV64, /// Divide input clock by 64 72 TMR_PRES_128 = MXC_S_TMR_CN_PRES_DIV128, /// Divide input clock by 128 73 TMR_PRES_256 = MXC_F_TMR_CN_PRES3 | MXC_S_TMR_CN_PRES_DIV1, /// Divide input clock by 256 74 TMR_PRES_512 = MXC_F_TMR_CN_PRES3 | MXC_S_TMR_CN_PRES_DIV2, /// Divide input clock by 512 75 TMR_PRES_1024 = MXC_F_TMR_CN_PRES3 | MXC_S_TMR_CN_PRES_DIV4, /// Divide input clock by 1024 76 TMR_PRES_2048 = MXC_F_TMR_CN_PRES3 | MXC_S_TMR_CN_PRES_DIV8, /// Divide input clock by 2048 77 TMR_PRES_4096 = MXC_F_TMR_CN_PRES3 | MXC_S_TMR_CN_PRES_DIV16 /// Divide input clock by 4096 78 } tmr_pres_t; 79 80 /** 81 * @brief Timer modes 82 */ 83 typedef enum { 84 TMR_MODE_ONESHOT = MXC_V_TMR_CN_TMODE_ONESHOT, /// Timer Mode ONESHOT 85 TMR_MODE_CONTINUOUS = MXC_V_TMR_CN_TMODE_CONTINUOUS, /// Timer Mode CONTINUOUS 86 TMR_MODE_COUNTER = MXC_V_TMR_CN_TMODE_COUNTER, /// Timer Mode COUNTER 87 TMR_MODE_PWM = MXC_V_TMR_CN_TMODE_PWM, /// Timer Mode PWM 88 TMR_MODE_CAPTURE = MXC_V_TMR_CN_TMODE_CAPTURE, /// Timer Mode CAPTURE 89 TMR_MODE_COMPARE = MXC_V_TMR_CN_TMODE_COMPARE, /// Timer Mode COMPARE 90 TMR_MODE_GATED = MXC_V_TMR_CN_TMODE_GATED, /// Timer Mode GATED 91 TMR_MODE_CAPTURE_COMPARE = MXC_V_TMR_CN_TMODE_CAPTURECOMPARE /// Timer Mode CAPTURECOMPARE 92 } tmr_mode_t; 93 94 /** 95 * @brief Timer units of time enumeration 96 */ 97 typedef enum { 98 TMR_UNIT_NANOSEC = 0, /**< Nanosecond Unit Indicator. */ 99 TMR_UNIT_MICROSEC, /**< Microsecond Unit Indicator. */ 100 TMR_UNIT_MILLISEC, /**< Millisecond Unit Indicator. */ 101 TMR_UNIT_SEC, /**< Second Unit Indicator. */ 102 } tmr_unit_t; 103 104 /** 105 * @brief Timer Configuration 106 */ 107 typedef struct { 108 tmr_mode_t mode; /// Desired timer mode 109 uint32_t cmp_cnt; /// Compare register value in timer ticks 110 unsigned pol; /// Polarity (0 or 1) 111 } tmr_cfg_t; 112 113 /** 114 * @brief Timer PWM Configuration 115 */ 116 typedef struct { 117 unsigned pol; /// PWM polarity (0 or 1) 118 uint32_t per_cnt; /// PWM period in timer ticks 119 uint32_t duty_cnt; /// PWM duty in timer ticks 120 } tmr_pwm_cfg_t; 121 122 /* **** Definitions **** */ 123 124 /* **** Function Prototypes **** */ 125 126 /** 127 * @brief Initialize timer module clock. 128 * @param tmr Pointer to timer module to initialize. 129 * @param pres Prescaler value. 130 * @param sys_cfg System configuration object 131 * @return #E_NO_ERROR if successful, error code otherwise. 132 */ 133 int TMR_Init(mxc_tmr_regs_t *tmr, tmr_pres_t pres, const sys_cfg_tmr_t* sys_cfg); 134 135 /** 136 * @brief Shutdown timer module clock. 137 * @param tmr Pointer to timer module to initialize. 138 * @return #E_NO_ERROR if successful, error code otherwise. 139 */ 140 int TMR_Shutdown(mxc_tmr_regs_t *tmr); 141 142 /** 143 * @brief Enable the timer. 144 * @param tmr Pointer to timer module to initialize. 145 */ 146 void TMR_Enable(mxc_tmr_regs_t* tmr); 147 148 /** 149 * @brief Disable the timer. 150 * @param tmr Pointer to timer module to initialize. 151 */ 152 void TMR_Disable(mxc_tmr_regs_t* tmr); 153 154 /** 155 * @brief Configure the timer. 156 * @param tmr Pointer to timer module to initialize. 157 * @param cfg Pointer to timer configuration struct. 158 * @return #E_NO_ERROR if successful. 159 */ 160 int TMR_Config(mxc_tmr_regs_t *tmr, const tmr_cfg_t *cfg); 161 162 /** 163 * @brief Configure the timer for PWM operation. 164 * @param tmr Pointer to timer module to initialize. 165 * @param cfg Pointer to timer PWM configuration struct. 166 * @note Can cause a glitch if the Timer is currently running. 167 * @return #E_BAD_PARAM if duty_cnt > per_cnt. 168 */ 169 int TMR_PWMConfig(mxc_tmr_regs_t *tmr, const tmr_pwm_cfg_t *cfg); 170 171 /** 172 * @brief Set the timer duty cycle. 173 * @param tmr Pointer to timer module to initialize 174 * @param duty New duty cycle count 175 * @note Will block until safe to change the duty count. 176 * @return #E_BAD_PARAM if duty_cnt > per_cnt. 177 */ 178 int TMR_PWMSetDuty(mxc_tmr_regs_t *tmr, uint32_t duty); 179 180 /** 181 * @brief Set the timer period. 182 * @param tmr Pointer to timer module to initialize. 183 * @param per New period count. 184 * @note Will block until safe to change the period count. 185 * @return #E_BAD_PARAM if duty_cnt > per_cnt. 186 */ 187 int TMR_PWMSetPeriod(mxc_tmr_regs_t* tmr, uint32_t per); 188 189 /** 190 * @brief Get the timer compare count. 191 * @param tmr Pointer to timer module to initialize. 192 * @return Returns the current compare count. 193 */ 194 uint32_t TMR_GetCompare(mxc_tmr_regs_t* tmr); 195 196 /** 197 * @brief Get the timer capture count. 198 * @param tmr Pointer to timer module to initialize. 199 * @return Returns the most recent capture count. 200 */ 201 uint32_t TMR_GetCapture(mxc_tmr_regs_t* tmr); 202 203 /** 204 * @brief Get the timer count. 205 * @param tmr Pointer to timer module to initialize. 206 * @return Returns the current count. 207 */ 208 uint32_t TMR_GetCount(mxc_tmr_regs_t* tmr); 209 210 /** 211 * @brief Clear the timer interrupt. 212 * @param tmr Pointer to timer module to initialize. 213 */ 214 void TMR_IntClear(mxc_tmr_regs_t* tmr); 215 216 /** 217 * @brief Get the timer interrupt status. 218 * @param tmr Pointer to timer module to initialize. 219 * @return Returns the interrupt status. 1 if interrupt has occurred. 220 */ 221 uint32_t TMR_IntStatus(mxc_tmr_regs_t* tmr); 222 223 /** 224 * @brief Set the timer compare count. 225 * @param tmr Pointer to timer module to initialize. 226 * @param cmp_cnt New compare count. 227 * @note This function does not protect against output glitches in PWM mode. 228 * Use TMR_PWMSetPeriod when in PWM mode. 229 */ 230 void TMR_SetCompare(mxc_tmr_regs_t *tmr, uint32_t cmp_cnt); 231 232 /** 233 * @brief Set the timer count. 234 * @param tmr Pointer to timer module to initialize. 235 * @param cnt New count. 236 */ 237 void TMR_SetCount(mxc_tmr_regs_t *tmr, uint32_t cnt); 238 239 /** 240 * @brief Convert real time to timer ticks. 241 * @param tmr Pointer to timer module to initialize. 242 * @param time Number of units of time. 243 * @param units Which units of time you want to convert. 244 * @param ticks Pointer to store the number of ticks calculated. 245 * @return #E_NO_ERROR if successful, error code otherwise. 246 */ 247 int TMR_GetTicks(mxc_tmr_regs_t *tmr, uint32_t time, tmr_unit_t units, uint32_t *ticks); 248 249 /** 250 * @brief Convert timer ticks to real time. 251 * @param tmr Pointer to timer module to initialize. 252 * @param ticks Number of ticks. 253 * @param time Pointer to store number of units of time. 254 * @param units Pointer to store the units that time represents. 255 * @return #E_NO_ERROR if successful, error code otherwise. 256 */ 257 int TMR_GetTime(mxc_tmr_regs_t *tmr, uint32_t ticks, uint32_t *time, tmr_unit_t *units); 258 259 /**@} end of group tmr */ 260 261 #ifdef __cplusplus 262 } 263 #endif 264 265 #endif /* _TMR_H_ */ 266