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