us_ticker_api.h

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