Changeset 429 for EcnlProtoTool/trunk/asp3_dcre/mbed/hal/us_ticker_api.h
- Timestamp:
- Jul 3, 2020, 7:19:17 PM (4 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
EcnlProtoTool/trunk/asp3_dcre/mbed/hal/us_ticker_api.h
r321 r429 1 2 /** \addtogroup hal */ 3 /** @{*/ 1 4 /* mbed Microcontroller Library 2 5 * Copyright (c) 2006-2015 ARM Limited … … 18 21 19 22 #include <stdint.h> 20 #include " ticker_api.h"23 #include "hal/ticker_api.h" 21 24 22 25 #ifdef __cplusplus … … 25 28 26 29 /** 27 * \defgroup UsTicker Microseconds Ticker Functions 30 * \defgroup hal_us_ticker Microsecond Ticker 31 * Low level interface to the microsecond ticker of a target 32 * 33 * # Defined behavior 34 * * Has a reported frequency between 250KHz and 8MHz - Verified by test ::us_ticker_info_test 35 * * Has a counter that is at least 16 bits wide - Verified by test ::us_ticker_info_test 36 * * All behavior defined by the @ref hal_ticker_shared "ticker specification" 37 * 38 * # Undefined behavior 39 * * See the @ref hal_ticker_shared "ticker specification" 40 * 41 * @see hal_us_ticker_tests 42 * 28 43 * @{ 29 44 */ 30 45 46 /** 47 * \defgroup hal_us_ticker_tests Microsecond Ticker tests 48 * Tests to validate the proper implementation of the microsecond ticker 49 * 50 * To run the microsecond ticker hal tests use the command: 51 * 52 * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*,tests-mbed_hal-us_ticker* 53 * 54 * @see hal_ticker_tests 55 * 56 */ 57 58 /** 59 * \defgroup hal_ticker_shared Ticker Hal 60 * Low level interface to the ticker of a target 61 * 62 * # Defined behavior 63 * * The function ticker_init is safe to call repeatedly - Verified by test ::ticker_init_test 64 * * The function ticker_init allows the ticker to keep counting and disables the ticker interrupt - Verified by test ::ticker_init_test 65 * * Ticker frequency is non-zero and counter is at least 8 bits - Verified by ::ticker_info_test 66 * * The ticker rolls over at (1 << bits) and continues counting starting from 0 - Verified by ::ticker_overflow_test 67 * * The ticker counts at the specified frequency +- 10% - Verified by ::ticker_frequency_test 68 * * The ticker increments by 1 each tick - Verified by ::ticker_increment_test 69 * * The ticker interrupt fires only when the ticker times increments to or past the value set by ticker_set_interrupt. 70 * Verified by ::ticker_interrupt_test and ::ticker_past_test 71 * * It is safe to call ticker_set_interrupt repeatedly before the handler is called - Verified by ::ticker_repeat_reschedule_test 72 * * The function ticker_fire_interrupt causes ticker_irq_handler to be called immediately from interrupt context - 73 * Verified by ::ticker_fire_now_test 74 * * The ticker operations ticker_read, ticker_clear_interrupt, ticker_set_interrupt and ticker_fire_interrupt 75 * take less than 20us to complete - Verified by ::ticker_speed_test 76 * 77 * # Undefined behavior 78 * * Calling any function other than ticker_init before the initialization of the ticker 79 * * Whether ticker_irq_handler is called a second time if the time wraps and matches the value set by ticker_set_interrupt again 80 * * Calling ticker_set_interrupt with a value that has more than the supported number of bits 81 * * Calling any function other than us_ticker_init after calling us_ticker_free 82 * 83 * # Potential bugs 84 * * Drift due to reschedule - Verified by ::ticker_repeat_reschedule_test 85 * * Incorrect overflow handling of timers - Verified by ::ticker_overflow_test 86 * * Interrupting at a time of 0 - Verified by ::ticker_overflow_test 87 * * Interrupt triggered more than once - Verified by ::ticker_interrupt_test 88 * 89 * @ingroup hal_us_ticker 90 * @ingroup hal_lp_ticker 91 */ 92 93 /** 94 * \defgroup hal_ticker_tests Ticker Tests 95 * Tests to validate the proper implementation of a ticker 96 * 97 * To run the ticker hal tests use the command: 98 * 99 * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker* 100 * 101 * @ingroup hal_us_ticker 102 * @ingroup hal_lp_ticker 103 */ 104 105 106 typedef void (*ticker_irq_handler_type)(const ticker_data_t *const); 107 108 /** Set ticker IRQ handler 109 * 110 * @param ticker_irq_handler IRQ handler to be connected 111 * 112 * @return previous ticker IRQ handler 113 * 114 * @note by default IRQ handler is set to ::ticker_irq_handler 115 * @note this function is primarily for testing purposes and it's not required part of HAL implementation 116 * 117 */ 118 ticker_irq_handler_type set_us_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler); 119 31 120 /** Get ticker's data 32 121 * 33 * @return The low powerticker data34 */ 35 const ticker_data_t *get_us_ticker_data(void);122 * @return The microsecond ticker data 123 */ 124 const ticker_data_t *get_us_ticker_data(void); 36 125 37 126 … … 45 134 /** Initialize the ticker 46 135 * 136 * Initialize or re-initialize the ticker. This resets all the 137 * clocking and prescaler registers, along with disabling 138 * the compare interrupt. 139 * 140 * @note Initialization properties tested by ::ticker_init_test 141 * 142 * Pseudo Code: 143 * @code 144 * void us_ticker_init() 145 * { 146 * // Enable clock gate so processor can read TIMER registers 147 * POWER_CTRL |= POWER_CTRL_TIMER_Msk; 148 * 149 * // Disable the timer and ensure it is powered down 150 * TIMER_CTRL &= ~(TIMER_CTRL_ENABLE_Msk | TIMER_CTRL_COMPARE_ENABLE_Msk); 151 * 152 * // Configure divisors 153 * uint32_t prescale = SystemCoreClock / 1000000; 154 * TIMER_PRESCALE = prescale - 1; 155 * TIMER_CTRL |= TIMER_CTRL_ENABLE_Msk; 156 * 157 * // Install the interrupt handler 158 * NVIC_SetVector(TIMER_IRQn, (uint32_t)us_ticker_irq_handler); 159 * NVIC_EnableIRQ(TIMER_IRQn); 160 * } 161 * @endcode 47 162 */ 48 163 void us_ticker_init(void); 49 164 165 /** Deinitialize the us ticker 166 * 167 * Powerdown the us ticker in preparation for sleep, powerdown, or reset. 168 * 169 * After this function is called, no other ticker functions should be called 170 * except us_ticker_init(), calling any function other than init is undefined. 171 * 172 * @note This function stops the ticker from counting. 173 * 174 * Pseudo Code: 175 * @code 176 * uint32_t us_ticker_free() 177 * { 178 * // Disable timer 179 * TIMER_CTRL &= ~TIMER_CTRL_ENABLE_Msk; 180 * 181 * // Disable the compare interrupt 182 * TIMER_CTRL &= ~TIMER_CTRL_COMPARE_ENABLE_Msk; 183 * 184 * // Disable timer interrupt 185 * NVIC_DisableIRQ(TIMER_IRQn); 186 * 187 * // Disable clock gate so processor cannot read TIMER registers 188 * POWER_CTRL &= ~POWER_CTRL_TIMER_Msk; 189 * } 190 * @endcode 191 * 192 */ 193 void us_ticker_free(void); 194 50 195 /** Read the current counter 51 196 * 52 * @return The current timer's counter value in microseconds 197 * Read the current counter value without performing frequency conversions. 198 * If no rollover has occurred, the seconds passed since us_ticker_init() 199 * was called can be found by dividing the ticks returned by this function 200 * by the frequency returned by ::us_ticker_get_info. 201 * 202 * @return The current timer's counter value in ticks 203 * 204 * Pseudo Code: 205 * @code 206 * uint32_t us_ticker_read() 207 * { 208 * return TIMER_COUNT; 209 * } 210 * @endcode 53 211 */ 54 212 uint32_t us_ticker_read(void); … … 56 214 /** Set interrupt for specified timestamp 57 215 * 58 * @param timestamp The time in microseconds to be set 216 * @param timestamp The time in ticks to be set 217 * 218 * @note no special handling needs to be done for times in the past 219 * as the common timer code will detect this and call 220 * us_ticker_fire_interrupt() if this is the case 221 * 222 * @note calling this function with timestamp of more than the supported 223 * number of bits returned by ::us_ticker_get_info results in undefined 224 * behavior. 225 * 226 * Pseudo Code: 227 * @code 228 * void us_ticker_set_interrupt(timestamp_t timestamp) 229 * { 230 * TIMER_COMPARE = timestamp; 231 * TIMER_CTRL |= TIMER_CTRL_COMPARE_ENABLE_Msk; 232 * } 233 * @endcode 59 234 */ 60 235 void us_ticker_set_interrupt(timestamp_t timestamp); … … 62 237 /** Disable us ticker interrupt 63 238 * 239 * Pseudo Code: 240 * @code 241 * void us_ticker_disable_interrupt(void) 242 * { 243 * // Disable the compare interrupt 244 * TIMER_CTRL &= ~TIMER_CTRL_COMPARE_ENABLE_Msk; 245 * } 246 * @endcode 64 247 */ 65 248 void us_ticker_disable_interrupt(void); … … 67 250 /** Clear us ticker interrupt 68 251 * 252 * Pseudo Code: 253 * @code 254 * void us_ticker_clear_interrupt(void) 255 * { 256 * // Write to the ICR (interrupt clear register) of the TIMER 257 * TIMER_ICR = TIMER_ICR_COMPARE_Msk; 258 * } 259 * @endcode 69 260 */ 70 261 void us_ticker_clear_interrupt(void); 262 263 /** Set pending interrupt that should be fired right away. 264 * 265 * The ticker should be initialized prior calling this function. 266 * 267 * Pseudo Code: 268 * @code 269 * void us_ticker_fire_interrupt(void) 270 * { 271 * NVIC_SetPendingIRQ(TIMER_IRQn); 272 * } 273 * @endcode 274 */ 275 void us_ticker_fire_interrupt(void); 276 277 /** Get frequency and counter bits of this ticker. 278 * 279 * Pseudo Code: 280 * @code 281 * const ticker_info_t* us_ticker_get_info() 282 * { 283 * static const ticker_info_t info = { 284 * 1000000, // 1 MHz 285 * 32 // 32 bit counter 286 * }; 287 * return &info; 288 * } 289 * @endcode 290 */ 291 const ticker_info_t *us_ticker_get_info(void); 71 292 72 293 /**@}*/ … … 77 298 78 299 #endif 300 301 /** @}*/
Note:
See TracChangeset
for help on using the changeset viewer.