1 /*
2 * Copyright (c) 2011, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * */
32 /*
33 * ======== ITimer.xdc ========
34 *
35 *
36 */
37
38 /*
39 * See SequenceInTimerAPIs.txt for details on how to implement
40 * this interface
41 */
42
43 /*!
44 * ======== ITimer ========
45 * Interface for Timer Peripherals Manager.
46 */
47
48 interface ITimer
49 {
50 /*! Timer tick function prototype. */
51 typedef Void (*FuncPtr)(UArg);
52
53 /*! Const used to specify any timer */
54 const UInt ANY = ~0;
55
56 /*!
57 * Timer Start Modes.
58 *
59 * @c(StartMode_AUTO) 60 * Statically created/constructed Timers will be started in BIOS_start().
61 * Dynamically created Timers will start at create() time. This includes
62 * timers created before BIOS_start().
63 *
64 * @c(StartMode_USER) 65 * Timer will be started by the user using start().
66 */
67 enum StartMode {
68 StartMode_AUTO, /*! timer starts automatically */
69 StartMode_USER /*! timer will be started by user */
70 };
71
72 /*!
73 * Timer Run Modes.
74 *
75 * @c(RunMode_CONTINUOUS) 76 * Timer is periodic and runs continuously.
77 *
78 * @c(RunMode_ONESHOT) 79 * Timer runs for a single period value and stops
80 */
81
82 enum RunMode {
83 RunMode_CONTINUOUS, /*! periodic and continuous */
84 RunMode_ONESHOT /*! one-shot */
85 };
86
87 /*! Timer Status.
88 *
89 * @c(Status_INUSE) 90 * Timer is in use. A timer is marked in use from the time it gets
91 * created to the time it gets deleted.
92 *
93 * @c(Status_FREE) 94 * Timer is free and can be acquired using create.
95 */
96
97 enum Status {
98 Status_INUSE, /*! timer in use */
99 Status_FREE /*! timer is free */
100 };
101
102 /*! PeriodType
103 *
104 * @c(PeriodType_MICROSECS) 105 * Period value is in microseconds.
106 *
107 * @c(PeriodType_COUNTS) 108 * Period value is in counts.
109 */
110
111 enum PeriodType {
112 PeriodType_MICROSECS, /*! period in microsecs */
113 PeriodType_COUNTS /*! period in counts */
114 };
115
116 /*!
117 * ======== getNumTimers ========
118 * Returns number of timer peripherals on the platform.
119 *
120 * @b(returns) Number of timer peripherals.
121 */
122 @DirectCall
123 UInt getNumTimers();
124
125 /*!
126 * ======== getStatus ========
127 * Returns timer status (free or in use).
128 *
129 * @b(returns) timer status
130 */
131 @DirectCall
132 Status getStatus(UInt id);
133
134 /*!
135 * ======== startup ========
136 * @_nodoc 137 * Startup function to be called during BIOS_start which starts
138 * statically created timers with startMode = StartMode_AUTO.
139 */
140 @DirectCall
141 Void startup();
142
143 instance:
144
145 /*!
146 * ======== create ========
147 * Create a timer.
148 *
149 * Create could fail if timer peripheral is unavailable. To
150 * request any available timer use {@link #ANY} as the id.
151 * TimerId's are logical ids. The family-specific implementations
152 * map the ids to physical peripherals.
153 *
154 * @param(id) Timer id ranging from 0 to a platform specific value
155 * @param(tickFxn) function that runs upon timer expiry.
156 */
157 @DirectCall
158 create(Int id, FuncPtr tickFxn);
159
160 /*! Timer run mode. Default is {@link #RunMode_CONTINUOUS}. */
161 config RunMode runMode = RunMode_CONTINUOUS;
162
163 /*! Start mode. Default is {@link #StartMode_AUTO}. */
164 config StartMode startMode = StartMode_AUTO;
165
166 /*! Argument for tick function. Default is null. */
167 config UArg arg = null;
168
169 /*!
170 * Period of tick. Can be specified in timer counts or microseconds.
171 * Default is 0.
172 *
173 * The implementation of ITimer will support a period of UInt32
174 * timer counts and use pre-scalars if necessary.
175 */
176 config UInt32 period = 0;
177
178 /*! Period Type. Default is PeriodType_MICROSECS */
179 config PeriodType periodType = PeriodType_MICROSECS;
180
181 /*!
182 * Timer frequency.
183 *
184 * This parameter is meaningfull only on platforms where the timer clock
185 * can be changed. If value is left at zero, then default hookup of timer
186 * clock is assumed.
187 */
188 config xdc.runtime.Types.FreqHz extFreq = {lo:0, hi:0};
189
190 /*!
191 * ======== start ========
192 * Reloads and starts the timer.
193 *
194 * Thread safety must be observed when using the {@link #start}
195 * and {@link #stop} APIs to avoid possible miss-
196 * configuration of the timers and unintended behaviors.
197 * To protect against re-entrancy, surround the start/stop invocations
198 * with {@link ti.sysbios.hal.Hwi#disable Hwi_disable()} and
199 * {@link ti.sysbios.hal.Hwi#restore Hwi_restore()} calls:
200 *
201 * @p(code) 202 * // disable interrupts if an interrupt could lead to
203 * // another call to Timer_start().
204 * key = Hwi_disable();
205 * Timer_stop();
206 * ...
207 * Timer_start();
208 * Hwi_restore(key);
209 * @p 210 *
211 * @a(side effects) 212 * Enables the timer's interrupt.
213 */
214 @DirectCall
215 Void start();
216
217 /*!
218 * ======== stop ========
219 * Stop the timer.
220 *
221 * Thread safety must be observed when using the {@link #start}
222 * and {@link #stop} APIs to avoid possible miss-
223 * configuration of the timers and unintended behaviors.
224 * To protect against re-entrancy, surround the start/stop invocations
225 * with {@link ti.sysbios.hal.Hwi#disable Hwi_disable()} and
226 * {@link ti.sysbios.hal.Hwi#restore Hwi_restore()} calls:
227 *
228 * @p(code) 229 * // disable interrupts if an interrupt could lead to
230 * // another call to Timer_start().
231 * key = Hwi_disable();
232 * Timer_stop();
233 * ...
234 * Timer_start();
235 * Hwi_restore(key);
236 * @p 237 *
238 * @a(side effects) 239 * Disables the timer's interrupt.
240 */
241 @DirectCall
242 Void stop();
243
244 /*!
245 * ======== setPeriod ========
246 * Sets timer period specified in timer counts.
247 *
248 * Timer_setPeriod() invokes Timer_stop() prior to setting the period
249 * and leaves the timer in the stopped state.
250 *
251 * To dynamically change the period of a timer you must
252 * protect against re-entrancy by disabling interrupts.
253 * Use the following call sequence to guarantee proper results:
254 *
255 * @p(code) 256 * // disable interrupts if an interrupt could lead to
257 * // another call to Timer_start().
258 * key = Hwi_disable();
259 * Timer_setPeriod(period);
260 * Timer_start();
261 * Hwi_restore(key);
262 * @p 263 *
264 * ITimer implementation must support UInt32 and use pre-scalars whenever
265 * necessary
266 *
267 * @a(side effects) 268 * Calls Timer_stop(), and disables the timer's interrupt.
269 *
270 * @param(period) period in timer counts
271 */
272 @DirectCall
273 Void setPeriod(UInt32 period);
274
275 /*!
276 * ======== setPeriodMicroSecs ========
277 * Sets timer period specified in microseconds.
278 *
279 * A best-effort method will be used to set the period register.
280 * There might be a slight rounding error based on resolution of timer
281 * period register. If the timer frequency cannot support the requested
282 * period, ie the timer period register cannot support the requested
283 * period, then this function returns false.
284 *
285 * Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting
286 * the period and leaves the timer in the stopped state.
287 *
288 * To dynamically change the period of a timer you must
289 * protect against re-entrancy by disabling interrupts.
290 * Use the following call sequence to guarantee proper results:
291 *
292 * @p(code) 293 * // disable interrupts if an interrupt could lead to
294 * // another call to Timer_start().
295 * key = Hwi_disable();
296 * Timer_setPeriodMicroSecs(period);
297 * Timer_start();
298 * Hwi_restore(key);
299 * @p 300 *
301 * @param(period) period in microseconds
302 */
303 @DirectCall
304 Bool setPeriodMicroSecs(UInt32 microsecs);
305
306 /*!
307 * ======== getPeriod ========
308 * Gets timer period in timer counts.
309 *
310 * @b(returns) period in timer counts
311 */
312 @DirectCall
313 UInt32 getPeriod();
314
315 /*!
316 * ======== getCount ========
317 * Reads timer counter register.
318 *
319 * @b(returns) timer counter value
320 */
321 @DirectCall
322 UInt32 getCount();
323
324 /*!
325 * ======== getFreq ========
326 * Returns timer frequency in Hz.
327 *
328 * This is the effective frequency of the clock incrementing the timer
329 * counter register after all scaling factors are taken into account.
330 * (including pre-scalars).
331 *
332 * @param(freq) frequency in Hz
333 */
334 @DirectCall
335 Void getFreq(xdc.runtime.Types.FreqHz *freq);
336
337 /*!
338 * ======== getFunc ========
339 * Get Timer function and arg
340 *
341 * @param(arg) pointer for returning Timer's function argument
342 * @b(returns) Timer's function
343 */
344 @DirectCall
345 FuncPtr getFunc(UArg *arg);
346
347 /*!
348 * ======== setFunc ========
349 * Overwrite Timer function and arg
350 *
351 * Replaces a Timer object's tickFxn function originally
352 * provided in {@link #create}.
353 *
354 * @param(fxn) pointer to function
355 * @param(arg) argument to function
356 */
357 @DirectCall
358 Void setFunc(FuncPtr fxn, UArg arg);
359
360 /*!
361 * ======== trigger ========
362 * @_nodoc 363 * Timer runs for specified number of cycles. The runMode
364 * must be Mode_ONESHOT.
365 *
366 * This function should interrupt the cpu after specified number of
367 * cpu cycles.
368 *
369 * The last instruction of trigger will start the timer. Depending on how
370 * the code is compiled, there may be one or more instructions in between
371 * the timer start and client code. The number of instructions specified
372 * is counted from when the timer is started.
373 *
374 * @param(instructions) cpu cycles
375 */
376 @DirectCall
377 Void trigger(UInt32 cycles);
378
379 /*!
380 * ======== getExpiredCounts ========
381 * @_nodoc 382 * Reads timer counter and adds period if IFR was set
383 * before counter read. Used exclusively by TimestampProvider.
384 *
385 * Must be called with interrupts disabled.
386 *
387 * @b(returns) expired counts.
388 */
389 @DirectCall
390 UInt32 getExpiredCounts();
391
392 }
393 /*
394 * @(#) ti.sysbios.interfaces; 2, 0, 0, 0,452; 2-2-2011 15:07:07; /db/vtree/library/trees/avala/avala-o27x/src/ xlibrary
395 396 */
397