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 /** @}*/