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 void us_ticker_free(void);
00175 
00176 /** Read the current counter
00177  *
00178  * Read the current counter value without performing frequency conversions.
00179  * If no rollover has occurred, the seconds passed since us_ticker_init()
00180  * was called can be found by dividing the ticks returned by this function
00181  * by the frequency returned by ::us_ticker_get_info.
00182  *
00183  * @return The current timer's counter value in ticks
00184  *
00185  * Pseudo Code:
00186  * @code
00187  * uint32_t us_ticker_read()
00188  * {
00189  *     return TIMER_COUNT;
00190  * }
00191  * @endcode
00192  */
00193 uint32_t us_ticker_read(void);
00194 
00195 /** Set interrupt for specified timestamp
00196  *
00197  * @param timestamp The time in ticks to be set
00198  *
00199  * @note no special handling needs to be done for times in the past
00200  * as the common timer code will detect this and call
00201  * us_ticker_fire_interrupt() if this is the case
00202  *
00203  * @note calling this function with timestamp of more than the supported
00204  * number of bits returned by ::us_ticker_get_info results in undefined
00205  * behavior.
00206  *
00207  * Pseudo Code:
00208  * @code
00209  * void us_ticker_set_interrupt(timestamp_t timestamp)
00210  * {
00211  *     TIMER_COMPARE = timestamp;
00212  *     TIMER_CTRL |= TIMER_CTRL_COMPARE_ENABLE_Msk;
00213  * }
00214  * @endcode
00215  */
00216 void us_ticker_set_interrupt(timestamp_t timestamp);
00217 
00218 /** Disable us ticker interrupt
00219  *
00220  * Pseudo Code:
00221  * @code
00222  * void us_ticker_disable_interrupt(void)
00223  * {
00224  *     // Disable the compare interrupt
00225  *     TIMER_CTRL &= ~TIMER_CTRL_COMPARE_ENABLE_Msk;
00226  * }
00227  * @endcode
00228  */
00229 void us_ticker_disable_interrupt(void);
00230 
00231 /** Clear us ticker interrupt
00232  *
00233  * Pseudo Code:
00234  * @code
00235  * void us_ticker_clear_interrupt(void)
00236  * {
00237  *     // Write to the ICR (interrupt clear register) of the TIMER
00238  *     TIMER_ICR = TIMER_ICR_COMPARE_Msk;
00239  * }
00240  * @endcode
00241  */
00242 void us_ticker_clear_interrupt(void);
00243 
00244 /** Set pending interrupt that should be fired right away.
00245  *
00246  * The ticker should be initialized prior calling this function.
00247  *
00248  * Pseudo Code:
00249  * @code
00250  * void us_ticker_fire_interrupt(void)
00251  * {
00252  *     NVIC_SetPendingIRQ(TIMER_IRQn);
00253  * }
00254  * @endcode
00255  */
00256 void us_ticker_fire_interrupt(void);
00257 
00258 /** Get frequency and counter bits of this ticker.
00259  *
00260  * Pseudo Code:
00261  * @code
00262  * const ticker_info_t* us_ticker_get_info()
00263  * {
00264  *     static const ticker_info_t info = {
00265  *         1000000,    // 1 MHz
00266  *         32          // 32 bit counter
00267  *     };
00268  *     return &info;
00269  * }
00270  * @endcode
00271  */
00272 const ticker_info_t* us_ticker_get_info(void);
00273 
00274 /**@}*/
00275 
00276 #ifdef __cplusplus
00277 }
00278 #endif
00279 
00280 #endif
00281 
00282 /** @}*/