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