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