bd6580c283b8125326471c48b23a8796bfb01487
1 /******************************************************************************
2 @file timer.h
4 @brief TIMAC 2.0 API timer implimentation
6 Group: WCS LPC
7 $Target Devices: Linux: AM335x, Embedded Devices: CC1310, CC1350$
9 ******************************************************************************
10 $License: BSD3 2016 $
12 Copyright (c) 2015, Texas Instruments Incorporated
13 All rights reserved.
15 Redistribution and use in source and binary forms, with or without
16 modification, are permitted provided that the following conditions
17 are met:
19 * Redistributions of source code must retain the above copyright
20 notice, this list of conditions and the following disclaimer.
22 * Redistributions in binary form must reproduce the above copyright
23 notice, this list of conditions and the following disclaimer in the
24 documentation and/or other materials provided with the distribution.
26 * Neither the name of Texas Instruments Incorporated nor the names of
27 its contributors may be used to endorse or promote products derived
28 from this software without specific prior written permission.
30 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
31 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
32 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
33 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
34 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
35 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
36 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
37 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
38 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
39 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
40 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
41 ******************************************************************************
42 $Release Name: TI-15.4Stack Linux x64 SDK$
43 $Release Date: July 14, 2016 (2.00.00.30)$
44 *****************************************************************************/
46 #if !defined(TIMER_H)
47 #define TIMER_H
49 #include "compiler.h"
51 /*!
52 * OVERVIEW
53 * ========================================
54 *
55 * <b>IMPORTANT:</b>
56 * ABS = Wall Clock time.
57 * nonABS = Time since the application started.
58 *
59 * Unless otherwise specified (ie: uSecs), time values are in milliseconds
60 * and will wrap after 47days of continous operation
61 * meaning: 2^32 milliseconds = 47 days.
62 *
63 * Pseudo timeout timers longer then (47days/2) = about 23 days are not
64 * supported. This code does not have a problem executing for over 47 days
65 *
66 * It does not have this famous bug:
67 * https://support.microsoft.com/en-us/kb/216641
68 *
69 *========================================
70 *
71 */
73 #include <stdint.h>
74 #include <stdbool.h>
76 /*!
77 * @brief Initialize the timer module
78 */
79 void TIMER_init(void);
81 /*!
82 * @brief retrieve the application epoch.
83 *
84 * The epoch is the time the application started in milliseconds
85 *
86 * For example:
87 * - Fri Dec 18 16:18:39 PST 2015
88 * - Is 1450484319000
89 *
90 * reference:
91 * http://www.merriam-webster.com/dictionary/epoch
92 *
93 * @returns the epoch
94 */
95 uint64_t TIMER_getEpoch(void);
97 /*!
98 * @brief Get the run time in mSecs from the epoch
99 *
100 * See note above about integer rollover.
101 * The main purpose of this function is to debug-print the current time
102 *
103 * @returns runtime in mSecs since the epoch
104 */
105 uint32_t TIMER_getNow(void);
107 /*!
108 * @brief Get wall-clocktime, as reported by the system
109 *
110 * @returns wallclock time in milliseconds as reported by the system.
111 */
112 uint64_t TIMER_getAbsNow(void);
114 /*!
115 * @brief A timer token.
116 *
117 * Timer tokens is a low cost way of creating a timeout timer
118 * this type of timer is good for polling timeouts
119 *
120 * If you require a timer with a callback, then use TIMER_CB_create()
121 *
122 * The return value does not need to be destroyed or released.
123 */
124 typedef uint32_t timertoken_t;
126 /*!
127 * @brief Get a timer token
128 *
129 * @return timer token.
130 *
131 * Example usage:
132 *
133 * \code
134 *
135 * token = TIMER_TimeoutStart()
136 *
137 * for(;;){
138 * r = poll_something();
139 * if(r == success){
140 * break;
141 * }
142 * if(TIMER_TimeoutIsExpired(token, 1000)){
143 * printf("One second timeout has expired\n");
144 * r = failure;
145 * }
146 * }
147 *
148 * \endcode
149 */
150 timertoken_t TIMER_timeoutStart(void);
152 /*!
153 * @brief Sleep for n-milliseconds
154 *
155 * @param number of milliseconds to sleep
156 *
157 * Notes:
158 * - 32bit machines cannot sleep more then (47days/2)
159 * - 16bit machines cannot sleep more then (16 seconds)
160 */
161 void TIMER_sleep(uint32_t nMsecs);
163 /*!
164 * @brief Determine if a timeout has expired
165 *
166 * @param token - from TIMER_TimeoutStart()
167 * @param n_msecs - how many milliseconds to test against.
168 *
169 * Note: if msecs == 0, the timeout is immediate
170 * if msecs == -1, the timeout is never
171 * if msecs > 0, timeout depends
172 */
173 int TIMER_timeoutIsExpired(timertoken_t token, int n_msecs);
175 /*!
176 * @typedef timer_callback
177 *
178 * @brief Timers done via a callback.
179 * @param h - the handle for this timer
180 * @param cookie - parameter for the timer callback.
181 * @return void
182 */
183 typedef void timer_callback_fn(intptr_t tmr_h, intptr_t cookie);
185 /*
186 * @brief Create a callback timer that occurs every n_mSecs
187 *
188 * @param pCbFunc - callback functions pointer
189 * @param dbg_name - name for debug purposes
190 * @param cookie - parameter for the callback function
191 * @param mSec_period - delay between callbacks measured in mSecs
192 * @param periodic - true if the timer should self-reschedule it self.
193 *
194 * As with the non-callback timer, the period ranges from
195 * 0 .. (UINT32_MAX/2) in milliseconds.
196 * This amounts to approximately 22 days on a 32bit machine.
197 *
198 * @return non-zero handle upon success, 0 on failure.
199 */
200 intptr_t TIMER_CB_create(const char *dbg_name,
201 timer_callback_fn *pCbFunc,
202 intptr_t cookie,
203 uint32_t mSec_Period,
204 bool periodic);
206 /*
207 * @brief cancel and release resources associate with this callback timer
208 *
209 * @param h - return handle from timer_cb_create()
210 */
211 void TIMER_CB_destroy(intptr_t h);
213 /*
214 * @brief Is this timer handle?
215 *
216 * @param h - return handle from timer_cb_create()
217 *
218 * @returns true if the handle is valid
219 */
220 bool TIMER_CB_isValid(intptr_t h);
222 /*
223 * @brief Is this timer handle?
224 *
225 * @param h - return handle from timer_cb_create()
226 *
227 * @returns negative if timer has expired, 0..N milliseconds remaining
228 *
229 */
230 int TIMER_CB_getRemain(intptr_t h);
232 #endif
234 /*
235 * ========================================
236 * Texas Instruments Micro Controller Style
237 * ========================================
238 * Local Variables:
239 * mode: c
240 * c-file-style: "bsd"
241 * tab-width: 4
242 * c-basic-offset: 4
243 * indent-tabs-mode: nil
244 * End:
245 * vim:set filetype=c tabstop=4 shiftwidth=4 expandtab=true
246 */