ticker_api_tests.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017-2017 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /** \addtogroup hal_ticker_tests */
00018 /** @{*/
00019 
00020 #ifndef TICKER_API_TESTS_H
00021 #define TICKER_API_TESTS_H
00022 
00023 #include "device.h"
00024 
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 /** Test that ticker_init can be called multiple times and
00031  * ticker_init resets the internal count and disables the ticker interrupt.
00032  *
00033  * Given ticker is initialised and interrupt is set.
00034  * When ticker is re-initialised.
00035  * Then ticker keeps counting and disables the ticker interrupt.
00036  */
00037 void ticker_init_test(void);
00038 
00039 /** Test that ticker frequency is non-zero and counter is at least 8 bits
00040  *
00041  * Given ticker is available.
00042  * When ticker information data is obtained.
00043  * Then ticker information indicate that frequency is non-zero and counter is at least 8 bits.
00044  */
00045 void ticker_info_test(void);
00046 
00047 /** Test that the ticker increments by one on each tick.
00048  *
00049  * We have the following assumption for the timer clock frequency:
00050  *
00051  * NOTE:
00052  * high freq ticker: 250 KHz (1 tick per 4 us) - 8 Mhz (1 tick per 1/8 us)
00053  * low power ticker: 8 KHz (1 tick per 125 us) - 64 KHz (1 tick per ~15.6 us)
00054  *
00055  * Lowest CPU speed is 16 MHz (1 tick per 1/16 us).
00056  *
00057  * For the boards with ticker clock freq less than or equal to 250 KHz we will try to prove that ticker is incremented by one
00058  * straightforward by reading ticker count value in the loop in order to detect a single ticker value update (hopefully by one).
00059  * For faster tickers we need to prove this indirectly using additional count_ticks() function which returns number of
00060  * ticks needed to perform N cycles of the empty while loop. For the same number of cycles function result should be the same with
00061  * accuracy +/- 1 tick. After the first test we will call count_ticks again with number of cycles equal N, N+1, N+2, ...
00062  * until we get other ticks result.
00063  *
00064  * Given ticker is available.
00065  * When ticker is initialised.
00066  * Then ticker counter is incremented by one.
00067  */
00068 void ticker_increment_test(void);
00069 
00070 /** Test that ticker interrupt fires only when the ticker counter increments to the value set by ticker_set_interrupt.
00071  *
00072  * Given ticker is available, initialised.
00073  * When ticker interrupt is set.
00074  * Then ticker interrupt fires at the valid time.
00075  */
00076 void ticker_interrupt_test(void);
00077 
00078 /** Test that ticker interrupt is not triggered when ticker_set_interrupt is called with a time from the past
00079  *
00080  * Given ticker is available, initialised.
00081  * When ticker interrupt is set to the time in the past.
00082  * Then ticker interrupt is not triggered.
00083  */
00084 void ticker_past_test(void);
00085 
00086 /** Test that ticker can be rescheduled repeatedly before the handler has been called.
00087  *
00088  * Given ticker is available, initialised.
00089  * When ticker interrupt is set and then rescheduled (interrupt time is modified).
00090  * Then ticker interrupt is triggered according the rescheduled time.
00091  */
00092 void ticker_repeat_reschedule_test(void);
00093 
00094 /** Test that ticker_fire_interrupt causes the interrupt to get fired immediately.
00095  *
00096  * Given ticker is available.
00097  * When ticker_fire_interrupt is called.
00098  * Then ticker interrupt is triggered.
00099  */
00100 void ticker_fire_now_test(void);
00101 
00102 /** Test that common ticker functions complete with the required amount of time.
00103  *
00104  * Given ticker is available.
00105  * When ticker_read, ticker_clear_interrupt, ticker_set_interrupt, ticker_fire_interrupt or ticker_disable_interrupt function is called.
00106  * Then its execution is not longer than 20 us.
00107  */
00108 void ticker_speed_test(void);
00109 
00110 /** Test that the ticker correctly handles overflow.
00111  *
00112  * Note that for high frequency timers we will only prove that ticker counter rollovers and
00113  * continue counting (it is not possible to prove in deterministic way that after rollover next value is 0).
00114  *
00115  * Given ticker is available.
00116  * When ticker has overflows.
00117  * Then ticker continues counting from the beginning and interrupt scheduling works.
00118  */
00119 void ticker_overflow_test(void);
00120 
00121 /**@}*/
00122 
00123 #ifdef __cplusplus
00124 }
00125 #endif
00126 
00127 #endif
00128 
00129 /**@}*/