1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 34 35 36
37
38 import xdc.runtime.Types;
39
40 41 42 43
44
45 /*!
46 * ======== ITimer ========
47 * Interface for Timer Peripherals Manager.
48 */
49
50 @DirectCall
51 @InstanceFinalize
52 @InstanceInitError
53
54 interface ITimer
55 {
56 /*! Timer tick function prototype */
57 typedef Void (*FuncPtr)(UArg);
58
59 /*! Const used to specify any timer */
60 const UInt ANY = ~0;
61
62 /*!
63 * Timer Start Modes
64 *
65 * @c(StartMode_AUTO)
66 * Statically created/constructed Timers will be started in BIOS_start().
67 * Dynamically created Timers will start at create() time. This includes
68 * timers created before BIOS_start().
69 *
70 * @c(StartMode_USER)
71 * Timer will be started by the user using start().
72 */
73 enum StartMode {
74 StartMode_AUTO, /*! timer starts automatically */
75 StartMode_USER /*! timer will be started by user */
76 };
77
78 /*!
79 * Timer Run Modes
80 *
81 * @c(RunMode_CONTINUOUS)
82 * Timer is periodic and runs continuously.
83 *
84 * @c(RunMode_ONESHOT)
85 * Timer runs for a single period value and stops.
86 *
87 * @c(RunMode_DYNAMIC)
88 * Timer is dynamically reprogrammed for the next required tick.
89 *
90 */
91 enum RunMode {
92 RunMode_CONTINUOUS, /*! periodic and continuous */
93 RunMode_ONESHOT, /*! one-shot */
94 RunMode_DYNAMIC /*! dynamically reprogrammed (available on subset of devices) */
95 };
96
97 /*!
98 * Timer Status
99 *
100 * @c(Status_INUSE)
101 * Timer is in use. A timer is marked in use from the time it gets
102 * created to the time it gets deleted.
103 *
104 * @c(Status_FREE)
105 * Timer is free and can be acquired using create.
106 */
107 enum Status {
108 Status_INUSE, /*! timer in use */
109 Status_FREE /*! timer is free */
110 };
111
112 /*!
113 * ======== PeriodType ========
114 * Timer period units
115 *
116 * @c(PeriodType_MICROSECS)
117 * Period value is in microseconds.
118 *
119 * @c(PeriodType_COUNTS)
120 * Period value is in counts.
121 */
122 enum PeriodType {
123 PeriodType_MICROSECS, /*! period in microsecs */
124 PeriodType_COUNTS /*! period in counts */
125 };
126
127 /*!
128 * @_nodoc
129 * Timer supports RunMode_DYNAMIC?
130 *
131 * Default is false. Can be overriden by Timer drivers that indeed
132 * support RunMode_DYNAMIC.
133 */
134 metaonly config Bool supportsDynamic = false;
135
136 /*!
137 * @_nodoc
138 * Default to RunMode_DYNAMIC?
139 *
140 * Default is false. Can be overriden by Timer drivers that support
141 * RunMode_DYNAMIC, who want DYNAMIC mode to be used by default.
142 */
143 metaonly config Bool defaultDynamic = false;
144
145 /*!
146 * ======== getNumTimers ========
147 * Returns number of timer peripherals on the platform.
148 *
149 * @b(returns) Number of timer peripherals.
150 */
151 UInt getNumTimers();
152
153 /*!
154 * ======== getStatus ========
155 * Returns timer status (free or in use).
156 *
157 * @b(returns) timer status
158 */
159 Status getStatus(UInt id);
160
161 /*!
162 * ======== startup ========
163 * @_nodoc
164 * Startup function to be called during BIOS_start
165 *
166 * This function starts statically created timers with
167 * startMode = StartMode_AUTO.
168 */
169 Void startup();
170
171 /*!
172 * @_nodoc
173 * ======== getFreqMeta ========
174 * Return timer frequency in Hz
175 *
176 * This is the effective frequency of the clock incrementing the timer
177 * counter register after all scaling factors are taken into account.
178 * (including pre-scalars).
179 */
180 metaonly Types.FreqHz getFreqMeta(UInt id);
181
182 instance:
183
184 /*!
185 * ======== create ========
186 * Create a timer.
187 *
188 * Create could fail if timer peripheral is unavailable. To
189 * request any available timer use {@link #ANY} as the id.
190 * TimerId's are logical ids. The family-specific implementations
191 * map the ids to physical peripherals.
192 *
193 * @param(id) Timer id ranging from 0 to a platform specific value,
194 * or {@link #ANY}
195 * @param(tickFxn) function that runs upon timer expiry.
196 */
197 create(Int id, FuncPtr tickFxn);
198
199 /*!
200 * Timer run mode
201 *
202 * Default is {@link #RunMode_CONTINUOUS}.
203 */
204 config RunMode runMode = RunMode_CONTINUOUS;
205
206 /*!
207 * Timer start mode
208 *
209 * Default is {@link #StartMode_AUTO}.
210 */
211 config StartMode startMode = StartMode_AUTO;
212
213 /*!
214 * Argument for tick function
215 *
216 * Default is null.
217 */
218 config UArg arg = null;
219
220 /*!
221 * Period of a tick
222 *
223 * The period can be specified in timer counts or microseconds
224 * and its default value is 0.
225 *
226 * The implementation of ITimer will support a period of UInt32
227 * timer counts and use pre-scalars if necessary.
228 */
229 config UInt32 period = 0;
230
231 /*!
232 * Period type
233 *
234 * Default is PeriodType_MICROSECS
235 */
236 config PeriodType periodType = PeriodType_MICROSECS;
237
238 /*!
239 * Timer frequency
240 *
241 * This parameter is meaningfull only on platforms where the timer's
242 * input clock can be changed. If value is left at zero, then input clock
243 * to the timer clock is assumed.
244 *
245 * This value is used to convert timer ticks to real time units; seconds,
246 * milliseconds, etc.
247 */
248 config xdc.runtime.Types.FreqHz extFreq = {lo:0, hi:0};
249
250 /*!
251 * @_nodoc
252 * ======== getMaxTicks ========
253 * Gets the maximum number of timer ticks that can be skipped (for Clock
254 * tick suppression), given the current timer configuration.
255 *
256 * This API is used internally by SYS/BIOS for dynamic Clock tick
257 * suppression. It is not intended to be used for any other purpose.
258 */
259 UInt32 getMaxTicks();
260
261 /*!
262 * @_nodoc
263 * ======== setNextTick ========
264 * Dynamically reprograms the timer with a new period value,
265 * corresponding to the tick value saved by the last getCurrentTick()
266 * call and the number of ticks passed.
267 *
268 * The timer is left running
269 * after the call, and it does not need to be stopped and restarted by
270 * the caller.
271 *
272 * This API is used internally by SYS/BIOS for dynamic Clock tick
273 * suppression. It is not intended to be used for any other purpose.
274 *
275 * @param(ticks) the corresponding number of ticks
276 */
277 Void setNextTick(UInt32 ticks);
278
279 /*!
280 * ======== start ========
281 * Reload and start the timer
282 *
283 * Thread safety must be observed when using the {@link #start}
284 * and {@link #stop} APIs to avoid possible miss-
285 * configuration of the timers and unintended behaviors.
286 * To protect against re-entrancy, surround the start/stop invocations
287 * with {@link ti.sysbios.hal.Hwi#disable Hwi_disable()} and
288 * {@link ti.sysbios.hal.Hwi#restore Hwi_restore()} calls:
289 *
290 * @p(code)
291 * // disable interrupts if an interrupt could lead to
292 * // another call to Timer_start().
293 * key = Hwi_disable();
294 * Timer_stop();
295 * ...
296 * Timer_start();
297 * Hwi_restore(key);
298 * @p
299 *
300 * @a(side effects)
301 * Enables the timer's interrupt.
302 */
303 Void start();
304
305 /*!
306 * ======== stop ========
307 * Stop the timer
308 *
309 * Thread safety must be observed when using the {@link #start}
310 * and {@link #stop} APIs to avoid possible miss-
311 * configuration of the timers and unintended behaviors.
312 * To protect against re-entrancy, surround the start/stop invocations
313 * with {@link ti.sysbios.hal.Hwi#disable Hwi_disable()} and
314 * {@link ti.sysbios.hal.Hwi#restore Hwi_restore()} calls:
315 *
316 * @p(code)
317 * // disable interrupts if an interrupt could lead to
318 * // another call to Timer_start().
319 * key = Hwi_disable();
320 * Timer_stop();
321 * ...
322 * Timer_start();
323 * Hwi_restore(key);
324 * @p
325 *
326 * @a(side effects)
327 * Disables the timer's interrupt.
328 */
329 Void stop();
330
331 /*!
332 * ======== setPeriod ========
333 * Set timer period specified in timer counts
334 *
335 * Timer_setPeriod() invokes Timer_stop() prior to setting the period
336 * and leaves the timer in the stopped state.
337 *
338 * To dynamically change the period of a timer you must
339 * protect against re-entrancy by disabling interrupts.
340 * Use the following call sequence to guarantee proper results:
341 *
342 * @p(code)
343 * // disable interrupts if an interrupt could lead to
344 * // another call to Timer_start().
345 * key = Hwi_disable();
346 * Timer_setPeriod(period);
347 * Timer_start();
348 * Hwi_restore(key);
349 * @p
350 *
351 * ITimer implementation must support UInt32 and use pre-scalars whenever
352 * necessary
353 *
354 * @a(side effects)
355 * Calls Timer_stop(), and disables the timer's interrupt.
356 *
357 * @param(period) period in timer counts
358 */
359 Void setPeriod(UInt32 period);
360
361 /*!
362 * ======== setPeriodMicroSecs ========
363 * Set timer period specified in microseconds.
364 *
365 * A best-effort method will be used to set the period register.
366 * There might be a slight rounding error based on resolution of timer
367 * period register. If the timer frequency cannot support the requested
368 * period, i.e. the timer period register cannot support the requested
369 * period, then this function returns false.
370 *
371 * Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting
372 * the period and leaves the timer in the stopped state.
373 *
374 * To dynamically change the period of a timer you must
375 * protect against re-entrancy by disabling interrupts.
376 * Use the following call sequence to guarantee proper results:
377 *
378 * @p(code)
379 * // disable interrupts if an interrupt could lead to
380 * // another call to Timer_start().
381 * key = Hwi_disable();
382 * Timer_setPeriodMicroSecs(period);
383 * Timer_start();
384 * Hwi_restore(key);
385 * @p
386 *
387 * @param(period) period in microseconds
388 */
389 Bool setPeriodMicroSecs(UInt32 microsecs);
390
391 /*!
392 * ======== getPeriod ========
393 * Get timer period in timer counts
394 *
395 * @b(returns) period in timer counts
396 */
397 UInt32 getPeriod();
398
399 /*!
400 * ======== getCount ========
401 * Read timer counter register
402 *
403 * @b(returns) timer counter value
404 */
405 UInt32 getCount();
406
407 /*!
408 * ======== getFreq ========
409 * Return timer frequency in Hz
410 *
411 * This is the effective frequency of the clock incrementing the timer
412 * counter register after all scaling factors are taken into account.
413 * (including pre-scalars).
414 *
415 * @param(freq) frequency in Hz
416 */
417 Void getFreq(xdc.runtime.Types.FreqHz *freq);
418
419 /*!
420 * ======== getFunc ========
421 * Get Timer function and arg
422 *
423 * @param(arg) pointer for returning Timer's function argument
424 * @b(returns) Timer's function
425 */
426 FuncPtr getFunc(UArg *arg);
427
428 /*!
429 * ======== setFunc ========
430 * Overwrite Timer function and arg
431 *
432 * Replaces a Timer object's tickFxn function originally
433 * provided in {@link #create}.
434 *
435 * @param(fxn) pointer to function
436 * @param(arg) argument to function
437 */
438 Void setFunc(FuncPtr fxn, UArg arg);
439
440 /*!
441 * ======== trigger ========
442 * Trigger timer function
443 *
444 * @_nodoc
445 * Timer runs for specified number of cycles. The runMode
446 * must be Mode_ONESHOT.
447 *
448 * This function should interrupt the cpu after specified number of
449 * cpu cycles.
450 *
451 * The last instruction of trigger will start the timer. Depending on how
452 * the code is compiled, there may be one or more instructions in between
453 * the timer start and client code. The number of instructions specified
454 * is counted from when the timer is started.
455 *
456 * @param(instructions) cpu cycles
457 */
458 Void trigger(UInt32 cycles);
459
460 /*!
461 * ======== getExpiredCounts ========
462 * Get current timer counter
463 *
464 * @_nodoc
465 * Reads timer counter and adds period if IFR was set
466 * before counter read. Used exclusively by TimestampProvider.
467 *
468 * Must be called with interrupts disabled.
469 *
470 * @b(returns) expired counts.
471 */
472 UInt32 getExpiredCounts();
473
474 /*!
475 * ======== getExpiredTicks ========
476 * Get the number of ticks that have elapsed since the last timer
477 * interrupt was serviced
478 *
479 * @_nodoc
480 * Reads timer counter and determines the number of virtual ticks that
481 * have elapsed given the specified tick period. This function is
482 * intended for use only by the Clock module, when using TickMode_DYNAMIC.
483 *
484 * Must be called with interrupts disabled.
485 *
486 * @b(returns) expired ticks.
487 */
488 UInt32 getExpiredTicks(UInt32 tickPeriod);
489
490 /*!
491 * ======== getCurrentTick ========
492 * Get the current tick number given a specific tick period.
493 *
494 * @_nodoc
495 * Reads timer counter and divides by the tickPeriod to return a
496 * corresponding tick number. This function is used by the Clock
497 * module on some targets when using TickMode_DYNAMIC.
498 *
499 * @param(save) true = save internal representation of currentTick
500 * for later use by setNextTick();
501 *
502 * @b(returns) tick number.
503 */
504 UInt32 getCurrentTick(Bool save);
505 }