mbed library sources. Supersedes mbed-src.
Dependents: Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more
us_ticker_api.h
00001 00002 /** \addtogroup hal */ 00003 /** @{*/ 00004 /* mbed Microcontroller Library 00005 * Copyright (c) 2006-2015 ARM Limited 00006 * SPDX-License-Identifier: Apache-2.0 00007 * 00008 * Licensed under the Apache License, Version 2.0 (the "License"); 00009 * you may not use this file except in compliance with the License. 00010 * You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, software 00015 * distributed under the License is distributed on an "AS IS" BASIS, 00016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00017 * See the License for the specific language governing permissions and 00018 * limitations under the License. 00019 */ 00020 #ifndef MBED_US_TICKER_API_H 00021 #define MBED_US_TICKER_API_H 00022 00023 #include <stdint.h> 00024 #include "hal/ticker_api.h" 00025 00026 #ifdef __cplusplus 00027 extern "C" { 00028 #endif 00029 00030 /** 00031 * \defgroup hal_us_ticker Microsecond Ticker 00032 * Low level interface to the microsecond ticker of a target 00033 * 00034 * # Defined behavior 00035 * * Has a reported frequency between 250KHz and 8MHz - Verified by test ::us_ticker_info_test 00036 * * Has a counter that is at least 16 bits wide - Verified by test ::us_ticker_info_test 00037 * * All behavior defined by the @ref hal_ticker_shared "ticker specification" 00038 * 00039 * # Undefined behavior 00040 * * See the @ref hal_ticker_shared "ticker specification" 00041 * 00042 * @see hal_us_ticker_tests 00043 * 00044 * @{ 00045 */ 00046 00047 /** 00048 * \defgroup hal_us_ticker_tests Microsecond Ticker tests 00049 * Tests to validate the proper implementation of the microsecond ticker 00050 * 00051 * To run the microsecond ticker hal tests use the command: 00052 * 00053 * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker*,tests-mbed_hal-us_ticker* 00054 * 00055 * @see hal_ticker_tests 00056 * 00057 */ 00058 00059 /** 00060 * \defgroup hal_ticker_shared Ticker Hal 00061 * Low level interface to the ticker of a target 00062 * 00063 * # Defined behavior 00064 * * The function ticker_init is safe to call repeatedly - Verified by test ::ticker_init_test 00065 * * The function ticker_init allows the ticker to keep counting and disables the ticker interrupt - Verified by test ::ticker_init_test 00066 * * Ticker frequency is non-zero and counter is at least 8 bits - Verified by ::ticker_info_test 00067 * * The ticker rolls over at (1 << bits) and continues counting starting from 0 - Verified by ::ticker_overflow_test 00068 * * The ticker counts at the specified frequency +- 10% - Verified by ::ticker_frequency_test 00069 * * The ticker increments by 1 each tick - Verified by ::ticker_increment_test 00070 * * The ticker interrupt fires only when the ticker times increments to or past the value set by ticker_set_interrupt. 00071 * Verified by ::ticker_interrupt_test and ::ticker_past_test 00072 * * It is safe to call ticker_set_interrupt repeatedly before the handler is called - Verified by ::ticker_repeat_reschedule_test 00073 * * The function ticker_fire_interrupt causes ticker_irq_handler to be called immediately from interrupt context - 00074 * Verified by ::ticker_fire_now_test 00075 * * The ticker operations ticker_read, ticker_clear_interrupt, ticker_set_interrupt and ticker_fire_interrupt 00076 * take less than 20us to complete - Verified by ::ticker_speed_test 00077 * 00078 * # Undefined behavior 00079 * * Calling any function other than ticker_init before the initialization of the ticker 00080 * * Whether ticker_irq_handler is called a second time if the time wraps and matches the value set by ticker_set_interrupt again 00081 * * Calling ticker_set_interrupt with a value that has more than the supported number of bits 00082 * * Calling any function other than us_ticker_init after calling us_ticker_free 00083 * 00084 * # Potential bugs 00085 * * Drift due to reschedule - Verified by ::ticker_repeat_reschedule_test 00086 * * Incorrect overflow handling of timers - Verified by ::ticker_overflow_test 00087 * * Interrupting at a time of 0 - Verified by ::ticker_overflow_test 00088 * * Interrupt triggered more than once - Verified by ::ticker_interrupt_test 00089 * 00090 * @ingroup hal_us_ticker 00091 * @ingroup hal_lp_ticker 00092 */ 00093 00094 /** 00095 * \defgroup hal_ticker_tests Ticker Tests 00096 * Tests to validate the proper implementation of a ticker 00097 * 00098 * To run the ticker hal tests use the command: 00099 * 00100 * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-common_ticker* 00101 * 00102 * @ingroup hal_us_ticker 00103 * @ingroup hal_lp_ticker 00104 */ 00105 00106 00107 typedef void (*ticker_irq_handler_type)(const ticker_data_t *const); 00108 00109 /** Set ticker IRQ handler 00110 * 00111 * @param ticker_irq_handler IRQ handler to be connected 00112 * 00113 * @return previous ticker IRQ handler 00114 * 00115 * @note by default IRQ handler is set to ::ticker_irq_handler 00116 * @note this function is primarily for testing purposes and it's not required part of HAL implementation 00117 * 00118 */ 00119 ticker_irq_handler_type set_us_ticker_irq_handler(ticker_irq_handler_type ticker_irq_handler); 00120 00121 /** Get ticker's data 00122 * 00123 * @return The microsecond ticker data 00124 */ 00125 const ticker_data_t *get_us_ticker_data(void); 00126 00127 00128 /** The wrapper for ticker_irq_handler, to pass us ticker's data 00129 * 00130 */ 00131 void us_ticker_irq_handler(void); 00132 00133 /* HAL us ticker */ 00134 00135 /** Initialize the ticker 00136 * 00137 * Initialize or re-initialize the ticker. This resets all the 00138 * clocking and prescaler registers, along with disabling 00139 * the compare interrupt. 00140 * 00141 * @note Initialization properties tested by ::ticker_init_test 00142 * 00143 * Pseudo Code: 00144 * @code 00145 * void us_ticker_init() 00146 * { 00147 * // Enable clock gate so processor can read TIMER registers 00148 * POWER_CTRL |= POWER_CTRL_TIMER_Msk; 00149 * 00150 * // Disable the timer and ensure it is powered down 00151 * TIMER_CTRL &= ~(TIMER_CTRL_ENABLE_Msk | TIMER_CTRL_COMPARE_ENABLE_Msk); 00152 * 00153 * // Configure divisors 00154 * uint32_t prescale = SystemCoreClock / 1000000; 00155 * TIMER_PRESCALE = prescale - 1; 00156 * TIMER_CTRL |= TIMER_CTRL_ENABLE_Msk; 00157 * 00158 * // Install the interrupt handler 00159 * NVIC_SetVector(TIMER_IRQn, (uint32_t)us_ticker_irq_handler); 00160 * NVIC_EnableIRQ(TIMER_IRQn); 00161 * } 00162 * @endcode 00163 */ 00164 void us_ticker_init(void); 00165 00166 /** Deinitialize the us ticker 00167 * 00168 * Powerdown the us ticker in preparation for sleep, powerdown, or reset. 00169 * 00170 * After this function is called, no other ticker functions should be called 00171 * except us_ticker_init(), calling any function other than init is undefined. 00172 * 00173 * @note This function stops the ticker from counting. 00174 * 00175 * Pseudo Code: 00176 * @code 00177 * uint32_t us_ticker_free() 00178 * { 00179 * // Disable timer 00180 * TIMER_CTRL &= ~TIMER_CTRL_ENABLE_Msk; 00181 * 00182 * // Disable the compare interrupt 00183 * TIMER_CTRL &= ~TIMER_CTRL_COMPARE_ENABLE_Msk; 00184 * 00185 * // Disable timer interrupt 00186 * NVIC_DisableIRQ(TIMER_IRQn); 00187 * 00188 * // Disable clock gate so processor cannot read TIMER registers 00189 * POWER_CTRL &= ~POWER_CTRL_TIMER_Msk; 00190 * } 00191 * @endcode 00192 * 00193 */ 00194 void us_ticker_free(void); 00195 00196 /** Read the current counter 00197 * 00198 * Read the current counter value without performing frequency conversions. 00199 * If no rollover has occurred, the seconds passed since us_ticker_init() 00200 * was called can be found by dividing the ticks returned by this function 00201 * by the frequency returned by ::us_ticker_get_info. 00202 * 00203 * @return The current timer's counter value in ticks 00204 * 00205 * Pseudo Code: 00206 * @code 00207 * uint32_t us_ticker_read() 00208 * { 00209 * return TIMER_COUNT; 00210 * } 00211 * @endcode 00212 */ 00213 uint32_t us_ticker_read(void); 00214 00215 /** Set interrupt for specified timestamp 00216 * 00217 * @param timestamp The time in ticks to be set 00218 * 00219 * @note no special handling needs to be done for times in the past 00220 * as the common timer code will detect this and call 00221 * us_ticker_fire_interrupt() if this is the case 00222 * 00223 * @note calling this function with timestamp of more than the supported 00224 * number of bits returned by ::us_ticker_get_info results in undefined 00225 * behavior. 00226 * 00227 * Pseudo Code: 00228 * @code 00229 * void us_ticker_set_interrupt(timestamp_t timestamp) 00230 * { 00231 * TIMER_COMPARE = timestamp; 00232 * TIMER_CTRL |= TIMER_CTRL_COMPARE_ENABLE_Msk; 00233 * } 00234 * @endcode 00235 */ 00236 void us_ticker_set_interrupt(timestamp_t timestamp); 00237 00238 /** Disable us ticker interrupt 00239 * 00240 * Pseudo Code: 00241 * @code 00242 * void us_ticker_disable_interrupt(void) 00243 * { 00244 * // Disable the compare interrupt 00245 * TIMER_CTRL &= ~TIMER_CTRL_COMPARE_ENABLE_Msk; 00246 * } 00247 * @endcode 00248 */ 00249 void us_ticker_disable_interrupt(void); 00250 00251 /** Clear us ticker interrupt 00252 * 00253 * Pseudo Code: 00254 * @code 00255 * void us_ticker_clear_interrupt(void) 00256 * { 00257 * // Write to the ICR (interrupt clear register) of the TIMER 00258 * TIMER_ICR = TIMER_ICR_COMPARE_Msk; 00259 * } 00260 * @endcode 00261 */ 00262 void us_ticker_clear_interrupt(void); 00263 00264 /** Set pending interrupt that should be fired right away. 00265 * 00266 * The ticker should be initialized prior calling this function. 00267 * 00268 * Pseudo Code: 00269 * @code 00270 * void us_ticker_fire_interrupt(void) 00271 * { 00272 * NVIC_SetPendingIRQ(TIMER_IRQn); 00273 * } 00274 * @endcode 00275 */ 00276 void us_ticker_fire_interrupt(void); 00277 00278 /** Get frequency and counter bits of this ticker. 00279 * 00280 * Pseudo Code: 00281 * @code 00282 * const ticker_info_t* us_ticker_get_info() 00283 * { 00284 * static const ticker_info_t info = { 00285 * 1000000, // 1 MHz 00286 * 32 // 32 bit counter 00287 * }; 00288 * return &info; 00289 * } 00290 * @endcode 00291 */ 00292 const ticker_info_t *us_ticker_get_info(void); 00293 00294 /**@}*/ 00295 00296 #ifdef __cplusplus 00297 } 00298 #endif 00299 00300 #endif 00301 00302 /** @}*/
Generated on Tue Jul 12 2022 20:41:16 by 1.7.2