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 package ti.sysbios.knl;
39
40 import xdc.rov.ViewInfo;
41
42 import xdc.runtime.Assert;
43 import xdc.runtime.Diags;
44 import xdc.runtime.Log;
45
46 /*!
47 * ======== Clock ========
48 * System Clock Manager
49 *
50 * The System Clock Manager is responsible for all timing services in
51 * SYS/BIOS.
52 * It generates the periodic system tick. The tick period is configurable.
53 * The timeout and period for all Clock Instances and timeout values in
54 * other SYS/BIOS modules are specified in terms of Clock ticks.
55 *
56 * The Clock Manager supports two tick "modes": a periodic mode with an
57 * interrupt on each tick (TickMode_PERIODIC), and a tick suppression
58 * mode (TickMode_DYNAMIC), which reduces the number of timer interrupts to
59 * the minimum required to support the scheduled timeouts. For devices that
60 * support it (e.g., MSP430 devices), TickMode_DYNAMIC may be the default
61 * mode if one is not specified in the application configuration; otherwise,
62 * the default mode will be TickMode_PERIODIC. The following example shows
63 * how the tick mode can be specified in the application configuration:
64 *
65 * @p(code)
66 * var Clock = xdc.useModule('ti.sysbios.knl.Clock');
67 *
68 * // Tell the Clock module to use TickMode_PERIODIC
69 * Clock.tickMode = Clock.TickMode_PERIODIC;
70 * @p
71 *
72 * Clock objects contain functions that can be scheduled to run after a
73 * certain number of Clock ticks.
74 * Clock objects are either one-shot or periodic. Instances are started
75 * when created or they are started later using the Clock_start() function.
76 * Instances can be stopped using the Clock_stop() function. All Clock
77 * Instances are executed when they expire in the context of a software
78 * interrupt.
79 *
80 * Clock objects are placed in the Clock object service list when
81 * created/constructed and remain there until deleted/destructed.
82 * To minimize processing overhead, unused or expired Clock objects
83 * should be deleted or destructed.
84 *
85 * By default, all Clock functions run in the context of a Swi.
86 * That is, the Clock module automatically creates a Swi for
87 * its use and runs the Clock functions within that Swi.
88 * The priority of the Swi used by Clock can be changed
89 * by configuring {@link #swiPriority Clock.swiPriority}.
90 *
91 * If Swis are disabled in an application
92 * (ie {@link ti.sysbios.BIOS#swiEnabled BIOS.swiEnabled} = false),
93 * then all Clock functions are executed within the context of
94 * a Timer Hwi.
95 *
96 * @a(Note)
97 * @p(blist)
98 * As Clock functions execute in either a Swi or Hwi context, they
99 * are not permitted to call blocking APIs.
100 * @p
101 * @a
102 *
103 * The getTicks() function returns number of clock ticks since startup.
104 *
105 * By default, the Timer module defined by {@link #TimerProxy} is used to
106 * statically create a timer instance that provides a periodic 1 ms
107 * tick interrupt.
108 *
109 * If you want to use a custom configured timer for the Clock module's
110 * tick source, use the following example configuration as a guide:
111 *
112 * @p(code)
113 * var Clock = xdc.useModule('ti.sysbios.knl.Clock');
114 *
115 * // Tell the Clock module that YOU are providing the periodic interrupt
116 * Clock.tickSource = Clock.TickSource_USER;
117 *
118 * // this example uses the ti.sysbios.timers.dmtimer.Timer module
119 * var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');
120 *
121 * // Change Timer 3 frequency to 24 Mhz from default if necessary
122 * Timer.intFreqs[3] = { hi:0, lo:24000000 };
123 *
124 * // create a dmtimer config parameter object
125 * var timerParams = new Timer.Params();
126 *
127 * // make sure you set the period to 1000 us (1ms)
128 * timerParams.period = 1000;
129 *
130 * // custom dmtimer config parameters here...
131 * timerParams.twer.ovf_wup_ena = 1;
132 *
133 * // Create the timer.
134 * // This example uses timer id 3.
135 * // Provide your own timer interrupt handler function.
136 * Timer.create(3, '&myTimerTick', timerParams);
137 * @p
138 *
139 * In your 'C' code, add your timer interrupt handler and have it
140 * call Clock_tick(), which will perform all of the Clock module
141 * tick duties:
142 *
143 * @p(code)
144 * #include <ti/sysbios/knl/Clock.h>
145 *
146 * Void myTimerTick(UArg arg)
147 * {
148 * Clock_tick();
149 * ...
150 * }
151 * @p
152 *
153 * @p(html)
154 * <h3> Calling Context </h3>
155 * <table border="1" cellpadding="3">
156 * <colgroup span="1"></colgroup> <colgroup span="5" align="center">
157 * </colgroup>
158 *
159 * <tr><th> Function </th><th> Hwi </th><th> Swi </th>
160 * <th> Task </th><th> Main </th><th> Startup </th></tr>
161 * <!-- -->
162 * <tr><td> {@link #construct} </td><td> N </td><td> N </td>
163 * <td> Y </td><td> Y </td><td> N </td></tr>
164 * <tr><td> {@link #create} </td><td> N </td><td> N </td>
165 * <td> Y </td><td> Y </td><td> N </td></tr>
166 * <tr><td> {@link #delete} </td><td> N </td><td> N </td>
167 * <td> Y </td><td> Y </td><td> N </td></tr>
168 * <tr><td> {@link #destruct} </td><td> N </td><td> N </td>
169 * <td> Y </td><td> Y </td><td> N </td></tr>
170 * <tr><td> {@link #getTicks} </td><td> Y </td><td> Y </td>
171 * <td> Y </td><td> N </td><td> N </td></tr>
172 * <tr><td> {@link #getTimerHandle} </td><td> Y </td><td> Y </td>
173 * <td> Y </td><td> Y </td><td> Y </td></tr>
174 * <tr><td> {@link #Params_init} </td><td> Y </td><td> Y </td>
175 * <td> Y </td><td> Y </td><td> Y </td></tr>
176 * <tr><td> {@link #tick} </td><td> Y </td><td> Y </td>
177 * <td> Y </td><td> N </td><td> N </td></tr>
178 * <tr><td> {@link #tickReconfig} </td><td> Y </td><td> Y </td>
179 * <td> Y </td><td> N </td><td> N </td></tr>
180 * <tr><td> {@link #tickStart} </td><td> Y </td><td> Y </td>
181 * <td> Y </td><td> N </td><td> N </td></tr>
182 * <tr><td> {@link #tickStop} </td><td> Y </td><td> Y </td>
183 * <td> Y </td><td> N </td><td> N </td></tr>
184 *
185 * <tr><td> {@link #getTimeout} </td><td> Y </td><td> Y </td>
186 * <td> Y </td><td> Y </td><td> N </td></tr>
187 * <tr><td> {@link #isActive} </td><td> Y </td><td> Y </td>
188 * <td> Y </td><td> Y </td><td> N </td></tr>
189 * <tr><td> {@link #setFunc} </td><td> Y </td><td> Y </td>
190 * <td> Y </td><td> Y </td><td> N </td></tr>
191 * <tr><td> {@link #setPeriod} </td><td> Y </td><td> Y </td>
192 * <td> Y </td><td> Y </td><td> N </td></tr>
193 * <tr><td> {@link #setTimeout} </td><td> Y </td><td> Y </td>
194 * <td> Y </td><td> Y </td><td> N </td></tr>
195 * <tr><td> {@link #start} </td><td> Y </td><td> Y </td>
196 * <td> Y </td><td> Y </td><td> N </td></tr>
197 * <tr><td> {@link #stop} </td><td> Y </td><td> Y </td>
198 * <td> Y </td><td> Y </td><td> N </td></tr>
199 * <tr><td colspan="6"> Definitions: <br />
200 * <ul>
201 * <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
202 * <li> <b>Swi</b>: API is callable from a Swi thread. </li>
203 * <li> <b>Task</b>: API is callable from a Task thread. </li>
204 * <li> <b>Main</b>: API is callable during any of these phases: </li>
205 * <ul>
206 * <li> In your module startup after this module is started
207 * (e.g. Clock_Module_startupDone() returns TRUE). </li>
208 * <li> During
209 * {@link xdc.runtime.Startup#lastFxns Startup.lastFxns}. </li>
210 * <li> During main().</li>
211 * <li> During
212 * {@link ti.sysbios.BIOS#startupFxns BIOS.startupFxns}.</li>
213 * </ul>
214 * <li> <b>Startup</b>: API is callable during any of these phases:</li>
215 * <ul>
216 * <li> During
217 * {@link xdc.runtime.Startup#firstFxns Startup.firstFxns}.</li>
218 * <li> In your module startup before this module is started
219 * (e.g. Clock_Module_startupDone() returns FALSE).</li>
220 * </ul>
221 * </ul>
222 * </td></tr>
223 *
224 * </table>
225 * @p
226 */
227
228 @DirectCall
229 @ModuleStartup
230 @InstanceInitStatic
231 @InstanceFinalize
232 @Template("./Clock.xdt")
233
234 module Clock
235 {
236 /*!
237 * ======== TickSource ========
238 * Clock tick source
239 *
240 * @field(TickSource_TIMER) The Clock module automatically configures a
241 * a Timer instance (see {@link #TimerProxy}) to drive the Clock tick.
242 * The specific timer and its period can be controlled via
243 * {@link #timerId} and {@link #tickPeriod}.
244 *
245 * @field(TickSource_USER) The Application is responsible for calling
246 * {@link #tick Clock_tick()} periodically. Make sure {@link #tickPeriod
247 * Clock.tickPeriod} is set to the period that Clock_tick() is called.
248 *
249 * Like most other module configuration parameters, the Clock.tickPeriod
250 * config parameter value is accessible in runtime C code as
251 * "Clock_tickPeriod".
252 *
253 * @field(TickSource_NULL) The Clock module is disabled.
254 * In this case, it is an error for the application to ever call
255 * Clock_tick().
256 *
257 * @see #tickPeriod
258 * @see #timerId
259 */
260 enum TickSource {
261 TickSource_TIMER, /*! Internally configure a Timer to periodically call Clock_tick() */
262 TickSource_USER, /*! Application code calls Clock_tick() */
263 TickSource_NULL /*! The Clock module is disabled */
264 };
265
266 /*!
267 * ======== TickMode ========
268 * Clock Tick Mode
269 */
270 enum TickMode {
271 TickMode_PERIODIC, /*! Timer will interrupt every period */
272 TickMode_DYNAMIC /*! Unnecessary timer ticks will be suppressed */
273 };
274
275 /*!
276 * ======== BasicView ========
277 * @_nodoc
278 */
279 metaonly struct BasicView {
280 String label;
281 UInt32 timeout;
282 UInt period;
283 String fxn[];
284 UArg arg;
285 Bool started;
286 String tRemaining;
287 Bool periodic;
288 }
289
290 /*!
291 * ======== ModuleView ========
292 * @_nodoc
293 */
294 metaonly struct ModuleView {
295 String ticks;
296 String tickSource;
297 String tickMode;
298 String timerHandle;
299 UInt timerId;
300 UInt swiPriority;
301 UInt32 tickPeriod;
302 volatile UInt nSkip;
303 }
304
305 306 307 308
309 @Facet
310 metaonly config ViewInfo.Instance rovViewInfo =
311 ViewInfo.create({
312 viewMap: [
313 ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
314 ['Module', {type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule', structName: 'ModuleView'}],
315 ]
316 });
317
318 /*!
319 * ======== FuncPtr ========
320 * Instance function prototype
321 */
322 typedef Void (*FuncPtr)(UArg);
323
324 /*!
325 * ======== TimerProxy ========
326 * target/device-specific Timer implementation.
327 *
328 * The Timer module used by the Clock module to
329 * create a Timer instance when Clock.tickSource_TIMER is configured.
330 *
331 * By default, a target specific Timer module is internally selected
332 * for this purpose. If the user wishes to use a different Timer module
333 * then the following configuration script will serve as an example for
334 * achieving that:
335 *
336 * @p(code)
337 * var Clock = xdc.useModule('ti.sysbios.knl.Clock');
338 *
339 * // Use a dmtimer Timer instance
340 * Clock.TimerProxy = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');
341 * @p
342 *
343 */
344 proxy TimerProxy inherits ti.sysbios.interfaces.ITimer;
345
346 /*!
347 * ======== LW_delayed ========
348 * Logged if Clock Swi delayed by >= 1 tick
349 */
350 config Log.Event LW_delayed = {
351 mask: Diags.USER3,
352 msg: "LW_delayed: delay: %d"
353 };
354
355 /*!
356 * ======== LM_tick ========
357 * Logged in every Clock tick interrupt
358 */
359 config Log.Event LM_tick = {
360 mask: Diags.USER1 | Diags.USER2,
361 msg: "LM_tick: tick: %d"
362 };
363
364 /*!
365 * ======== LM_begin ========
366 * Logged just prior to calling each Clock function
367 */
368 config Log.Event LM_begin = {
369 mask: Diags.USER1 | Diags.USER2,
370 msg: "LM_begin: clk: 0x%x, func: 0x%x"
371 };
372
373 /*!
374 * ======== A_clockDisabled ========
375 * Asserted in Clock_create()
376 */
377 config Assert.Id A_clockDisabled = {
378 msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
379 };
380
381 /*!
382 * ======== A_badThreadType ========
383 * Asserted in Clock_create and Clock_delete
384 */
385 config Assert.Id A_badThreadType = {
386 msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
387 };
388
389 /*!
390 * @_nodoc
391 * !!! Do not delete. Required for ROM compatibility !!!
392 */
393 config UInt32 serviceMargin = 0;
394
395 /*!
396 * ======== tickSource ========
397 * Source of clock ticks
398 *
399 * If this parameter is not set to TickSource_TIMER,
400 * {@link #tickStart Clock_tickStart()},
401 * {@link #tickStop Clock_tickStop()}, and
402 * {@link #tickReconfig Clock_tickReconfig()}, have no effect.
403 *
404 * The default is TickSource_TIMER.
405 */
406 config TickSource tickSource = TickSource_TIMER;
407
408 /*!
409 * ======== tickMode ========
410 * Timer tick mode
411 *
412 * This parameter specifies the tick mode to be used by the underlying
413 * Timer.
414 *
415 * With TickMode_PERIODIC the timer will interrupt the CPU at
416 * a fixed rate, defined by the tickPeriod.
417 *
418 * With TickMode_DYNAMIC the timer can be dynamically reprogrammed by
419 * Clock, to interrupt the CPU when the next tick is actually needed for
420 * a scheduled timeout. TickMode_DYNAMIC is not supported on all devices,
421 * and may have some application constraints (for example, for MSP430,
422 * see a description on this wiki page:
423 * https://processors.wiki.ti.com/index.php/SYS/BIOS_for_the_MSP430#Clock_Tick_Suppression).
424 */
425 config TickMode tickMode;
426
427 /*!
428 * ======== timerId ========
429 * Timer Id used to create a Timer instance
430 *
431 * If {@link #tickSource Clock.tickSource} is set to TickSource_TIMER,
432 * the Clock module internally creates a
433 * static Timer instance (see {@link #TimerProxy}) that automatically calls
434 * Clock_doTick() on a periodic basis (as specified by
435 * {@link #tickPeriod tickPeriod} and {@link #periodType periodType}.)
436 *
437 * This configuration parameter allows you to control which timer is
438 * used to drive the Clock module.
439 *
440 * The default value is {@link ti.sysbios.hal.Timer#ANY Timer.ANY} (~0)
441 * and the maximum timerId possible is family and device specific.
442 */
443 config UInt timerId = ~0;
444
445 /*!
446 * ======== swiPriority ========
447 * The priority of Swi used by Clock to process its instances
448 *
449 * All Clock instances are executed in the context of a single
450 * {@link Swi}. This parameter allows you to control the priority of
451 * that Swi.
452 *
453 * The default value of this parameter is Swi.numPriorities - 1; i.e.,
454 * the maximum Swi priority.
455 *
456 * @see ti.sysbios.knl.Swi#numPriorities
457 */
458 metaonly config UInt swiPriority;
459
460 /*!
461 * ======== tickPeriod ========
462 * Tick period specified in microseconds
463 *
464 * Default value is family dependent. For example, Linux systems often
465 * only support a minimum period of 10000 us and multiples of 10000 us.
466 * TI platforms have a default of 1000 us.
467 *
468 * Like most other module configuration parameters, the Clock.tickPeriod
469 * config parameter value is accessible in runtime C code as
470 * "Clock_tickPeriod".
471 */
472 config UInt32 tickPeriod;
473
474 /*!
475 * @_nodoc
476 * ======== stopCheckNext ========
477 * Boolean to control whether a check is made upon each Clock_stop() call
478 * to determine if the Clock object being stopped is due to timeout on the
479 * next scheduled tick. If this feature is enabled, and the timeout
480 * coincides with the next scheduled tick, then a special 'trigger' Clock
481 * will be started to force a reschedule of the next tick, as soon as
482 * possible. This feature is only applicable for Clock.TickMode_DYNAMIC.
483 *
484 * For most use cases it is most efficient to simply stop
485 * a Clock object, and then let the next scheduled tick occur naturally.
486 * But some low power application use cases (that routinely stop the next
487 * expiring Clock object) can benefit by scheduling an immediate tick, to
488 * suppress the next scheduled tick. The default value for most
489 * targets is 'false', for cc26xx/cc13xx it is 'true'. The default is
490 * established in Clock.xs, if the application has not explicitly
491 * specified a value.
492 */
493 metaonly config Bool stopCheckNext;
494
495 /*!
496 * ======== getTicks ========
497 * Time in Clock ticks
498 *
499 * The value returned will wrap back to zero after it reaches the max
500 * value that can be stored in 32 bits.
501 *
502 * @b(returns) time in clock ticks
503 */
504 UInt32 getTicks();
505
506 /*!
507 * @_nodoc
508 * ======== getTimerHandle ========
509 * Get timer Handle
510 *
511 * Used when it is necessary to change family
512 * specific options for the timer and its Hwi Object.
513 *
514 * @b(returns) Timer Handle
515 */
516 TimerProxy.Handle getTimerHandle();
517
518 /*!
519 * ======== tickStop ========
520 * Stop clock for reconfiguration
521 *
522 * This function is used to stop the timer used for generation of
523 * clock ticks. It is used along with Clock_tickStart() and
524 * Clock_tickReconfig() to allow reconfiguration of timer at runtime.
525 *
526 * Stopping the timer may not be supported for some types of timers, and
527 * is not supported for Clock.TickMode_DYNAMIC; in these cases, this
528 * this function call will have no effect.
529 *
530 * @a(constraints)
531 * This function is non-reentrant and appropriate locks must be used to
532 * protect against re-entrancy.
533 */
534 Void tickStop();
535
536 /*!
537 * ======== tickReconfig ========
538 * Reconfigure clock for new cpu frequency
539 *
540 * This function uses the new cpu frequency to reconfigure the timer used
541 * for generation of clock ticks such that tick period is
542 * accurate. This function is used along with Clock_tickStop() and
543 * Clock_tickStart() to allow reconfiguration of timer at runtime.
544 *
545 * Reconfiguration may not be supported for some types of timers, and is
546 * not supported for Clock.TickMode_DYNAMIC; in these cases, this
547 * this function call will have no effect, and will return false.
548 *
549 * When calling Clock_tickReconfig outside of main(), you must also call
550 * Clock_tickStop and Clock_tickStart to stop and restart the timer.
551 * Use the following call sequence:
552 *
553 * @p(code)
554 * // disable interrupts if an interrupt could lead to
555 * // another call to Clock_tickReconfig or if interrupt
556 * // processing relies on having a running timer
557 * Hwi_disable() or Swi_disable();
558 * BIOS_setCpuFreq(&freq);
559 * Clock_tickStop();
560 * Clock_tickReconfig();
561 * Clock_tickStart();
562 * Hwi_restore() or Swi_enable()
563 * @p
564 *
565 * When calling Clock_tickReconfig from main(), the timer has not yet
566 * been started because the timer is started as part of BIOS_start().
567 * As a result, you can use the following simplified call sequence
568 * in main():
569 *
570 * @p(code)
571 * BIOS_setCpuFrequency(Types.FreqHz *freq);
572 * Clock_tickReconfig(Void);
573 * @p
574 *
575 * The return value is false if the timer cannot support the new
576 * frequency
577 *
578 * @b(returns) true if successful
579 *
580 * @a(constraints)
581 * This function is non-reentrant and appropriate locks must be used to
582 * protect against re-entrancy.
583 */
584 Bool tickReconfig();
585
586 /*!
587 * ======== tickStart ========
588 * Start clock after reconfiguration
589 *
590 * This function starts the timer used for generation of clock ticks
591 * It is used along with Clock_tickStop() and Clock_tickReconfig() to
592 * allow reconfiguration of timer at runtime. The new timer configuration
593 * reflects changes caused by a call to reconfig().
594 *
595 * Reconfiguration and restart of a timer may not be supported for some
596 * types of timers, and is not supported for Clock.TickMode_DYNAMIC; in
597 * these cases, this function call will have no effect.
598 *
599 * @a(constraints)
600 * This function is non-reentrant and appropriate locks must be used to
601 * protect against re-entrancy.
602 */
603 Void tickStart();
604
605 /*!
606 * ======== tick ========
607 * Advance Clock time by one tick
608 *
609 * After incrementing a global tick counter, this function posts a Swi
610 * that processes the clock instances.
611 *
612 * This function is automatically called by a timer ISR when
613 * {@link #tickSource} is set to {@link #TickSource_TIMER}.
614 *
615 * When {@link #tickSource} is set to
616 * {@link #TickSource_USER}, Clock_tick() must be called by the
617 * application. Usually, this is done within a user defined {@link ti.sysbios.hal.Hwi Hwi},
618 * {@link Swi}, or {@link Task}.
619 *
620 * Note that this function is not re-entrant. The application is
621 * responsible for ensuring that invocations of this function are
622 * serialized: either only one thread in the system ever calls this
623 * function or all calls are "wrapped" by an appropriate mutex.
624 *
625 * @see #tickSource
626 */
627 Void tick();
628
629 /*!
630 * @_nodoc
631 * ======== workFunc ========
632 * Clock Q service routine
633 *
634 * @param(arg0) Unused. required to match Swi.FuncPtr
635 * @param(arg1) Unused. required to match Swi.FuncPtr
636 */
637 Void workFunc(UArg arg0, UArg arg1);
638
639 /*!
640 * @_nodoc
641 * ======== workFuncDynamic ========
642 * Clock Q service routine for TickMode_DYNAMIC
643 *
644 * @param(arg0) Unused. required to match Swi.FuncPtr
645 * @param(arg1) Unused. required to match Swi.FuncPtr
646 */
647 Void workFuncDynamic(UArg arg0, UArg arg1);
648
649 /*!
650 * @_nodoc
651 * ======= logTick ========
652 * Log the LD_tick from within Clock module scope
653 */
654 Void logTick();
655
656 /*!
657 * @_nodoc
658 * ======== getCompletedTicks ========
659 * Get the number of Clock ticks that have completed
660 *
661 * Returns the number of ticks completed, to the point where
662 * the underlying Timer interrupt has been serviced.
663 *
664 * Used by some TimestampProviders
665 *
666 * @b(returns) time in clock ticks
667 */
668 UInt32 getCompletedTicks();
669
670 /*!
671 * @_nodoc
672 * ======== getTickPeriod ========
673 * Get the Clock tick period in timer counts
674 *
675 * The period is in units returned by the underlying Timer.
676 *
677 * Used by some TimestampProviders
678 *
679 * @b(returns) period in timer counts
680 */
681 UInt32 getTickPeriod();
682
683 /*!
684 * @_nodoc
685 * ======== getTicksUntilInterrupt ========
686 * Get the number of Clock tick periods expected to expire between now
687 * and the next interrupt from the timer peripheral
688 *
689 * Used internally by Power modules.
690 *
691 * @b(returns) count in ticks
692 */
693 UInt32 getTicksUntilInterrupt();
694
695 /*!
696 * @_nodoc
697 * ======= walkQueueDynamic ========
698 * Walk Clock's work queue for TickMode_DYNAMIC
699 */
700 UInt32 walkQueueDynamic(Bool service, UInt32 tick);
701
702 /*!
703 * @_nodoc
704 * ======= scheduleNextTick ========
705 * Reprogram Clock's Timer for earliest required tick
706 */
707 Void scheduleNextTick(UInt32 deltaTicks, UInt32 absTick);
708
709 instance:
710
711 /*!
712 * ======== create ========
713 * Creates a Clock Instance
714 *
715 * The first argument is the function that gets called when the timeout
716 * expires.
717 *
718 * The 'timeout' argument is used to specify the initial timeout
719 * for both one-shot and periodic Clock instances (in Clock ticks).
720 *
721 * The {@link #period} parameter is used to set the subsequent timeout
722 * interval (in Clock ticks) for periodic instances.
723 *
724 * For one-shot instances, the period parameter must be set to zero.
725 *
726 * When instances are created they are placed upon a linked list managed
727 * by the Clock module. For this reason, instances cannot be created
728 * from either Hwi or Swi context.
729 *
730 * By default, all Clock functions run in the context of a Swi.
731 * That is, the Clock module automatically creates a Swi for
732 * its use and runs the Clock functions within that Swi.
733 * The priority of the Swi used by Clock can be changed
734 * by configuring {@link #swiPriority Clock.swiPriority}.
735 *
736 * If Swis are disabled in an application
737 * (ie {@link ti.sysbios.BIOS#swiEnabled BIOS.swiEnabled} = false),
738 * then all Clock functions are executed within the context of
739 * a Timer Hwi.
740 *
741 * @a(constraint)
742 * @p(blist)
743 * As Clock functions execute in either a Swi or Hwi context, they
744 * are not permitted to call blocking APIs.
745 * @p
746 * @a
747 *
748 * @param(clockFxn) Function that runs upon timeout
749 * @param(timeout) One-shot timeout or initial start delay (in clock
750 * ticks)
751 */
752 create(FuncPtr clockFxn, UInt timeout);
753
754 /*!
755 * ======== startFlag ========
756 * Start immediately after instance is created
757 *
758 * When this flag is set to false, the user will have to call
759 * Clock_start() to start the instance.
760 *
761 * When set to true, both statically created Clock objects and Clock
762 * objects created in main() are started at the end of main() when the
763 * user calls BIOS_start(). Dynamically created Clock objects created
764 * after main() (ie within a task) will be started immediately.
765 *
766 * The default setting for this parameter is false.
767 *
768 * The configured Clock function will be called initially after an
769 * interval equal to the 'timeout' argument for both one-shot and
770 * periodic Clock objects.
771 *
772 * Periodic Clock objects will subsequently be called at the rate
773 * specified by the {@link #period} parameter.
774 *
775 */
776 config Bool startFlag = false;
777
778 /*!
779 * ======== period ========
780 * Period of this instance (in clock ticks)
781 *
782 * The default value of this parameter is 0, which indicates this is
783 * a one-shot Clock object.
784 *
785 * A non zero value for this parameter specifies that the Clock
786 * object is to be called periodically, and also specifies the
787 * rate (in Clock ticks) that the Clock function will be called
788 * AFTER the initial 'timeout' argument period.
789 *
790 * For one-shot Clock instances, this parameter must be set to zero.
791 */
792 config UInt32 period = 0;
793
794 /*!
795 * ======== arg ========
796 * Uninterpreted argument passed to instance function
797 *
798 * The default is null.
799 */
800 config UArg arg = null;
801
802 /*!
803 * @_nodoc
804 * ======== addI ========
805 * Lightweight One-Shot Clock create for internal SYS/BIOS timeout APIs
806 * Does NOT start the timeout (ie requires Clock_startI() to be called)
807 * Does NOT assume Hwis are disabled
808 */
809 Void addI(FuncPtr clockFxn, UInt32 timeout, UArg arg);
810
811 /*!
812 * @_nodoc
813 * ======== removeI ========
814 * Lightweight Clock delete for internal SYS/BIOS timeout APIs
815 * Assumes Hwis are disabled
816 */
817 Void removeI();
818
819 /*!
820 * ======== start ========
821 * Start instance
822 *
823 * The {@link #timeout} and {@link #period} values set during create()
824 * or by calling Clock_setTimeout() and Clock_setPeriod() are used and
825 * the expiry is recomputed.
826 * Note that for periodic instances, the first expiry is
827 * computed using the timeout specified. All subsequent expiries use the
828 * period value.
829 *
830 * @a(constraints)
831 * Timeout of instance cannot be zero
832 */
833 Void start();
834
835 /*!
836 * @_nodoc
837 * ======== startI ========
838 * Internal start function which assumes Hwis disabled
839 */
840 Void startI();
841
842 /*!
843 * ======== stop ========
844 * Stop instance
845 */
846 Void stop();
847
848 /*!
849 * ======== setPeriod ========
850 * Set periodic interval
851 *
852 * @param(period) periodic interval in Clock ticks
853 *
854 * @a(constraints)
855 * Cannot change period of instance that has been started.
856 */
857 Void setPeriod(UInt32 period);
858
859 /*!
860 * ======== setTimeout ========
861 * Set the initial timeout
862 *
863 * @param(timeout) initial timeout in Clock ticks
864 *
865 * @a(constraints)
866 * Cannot change the initial timeout of instance that has been started.
867 */
868 Void setTimeout(UInt32 timeout);
869
870 /*!
871 * ======== setFunc ========
872 * Overwrite Clock function and arg
873 *
874 * Replaces a Clock object's clockFxn function originally
875 * provided in {@link #create}.
876 *
877 * @param(clockFxn) function of type FuncPtr
878 * @param(arg) argument to clockFxn
879 *
880 * @a(constraints)
881 * Cannot change function and arg of Clock object that has been started.
882 */
883 Void setFunc(FuncPtr fxn, UArg arg);
884
885 /*!
886 * ======== getPeriod ========
887 * Get period of instance
888 *
889 * Returns the period of an instance.
890 *
891 * @b(returns) returns periodic interval in Clock ticks
892 */
893 UInt32 getPeriod();
894
895 /*!
896 * ======== getTimeout ========
897 * Get timeout of instance
898 *
899 * Returns the remaining time if instance has been started.
900 *
901 * @b(returns) returns timeout in clock ticks
902 */
903 UInt32 getTimeout();
904
905 /*!
906 * ======== isActive ========
907 * Determine if Clock object is currently active (ie running)
908 *
909 * Returns TRUE if Clock object is currently active
910 *
911 * @b(returns) returns active state
912 */
913 Bool isActive();
914
915 internal:
916
917 918 919 920
921 metaonly config Bool timerSupportsDynamic = false;
922
923 924 925 926 927
928 config Void (*doTickFunc)(UArg);
929
930 /*!
931 * ======== doTick ========
932 * Function called by the timer interrupt handler
933 *
934 * @param(arg) Unused. Required to match signature of Hwi.FuncPtr
935 */
936 Void doTick(UArg arg);
937
938 939 940 941
942 config Clock.Handle triggerClock;
943
944 945 946 947
948 Void triggerFunc(UArg arg);
949
950 951 952
953 struct Instance_State {
954 Queue.Elem elem;
955 UInt32 timeout;
956 UInt32 currTimeout;
957 UInt32 period;
958 volatile Bool active;
959 FuncPtr fxn;
960 UArg arg;
961 };
962
963 964 965
966 struct Module_State {
967 volatile UInt32 ticks;
968 UInt swiCount;
969 TimerProxy.Handle timer;
970
971 Queue.Object clockQ;
972 Swi.Handle swi;
973 volatile UInt numTickSkip;
974 UInt32 nextScheduledTick;
975 UInt32 maxSkippable;
976 Bool inWorkFunc;
977 Bool startDuringWorkFunc;
978 Bool ticking;
979 };
980 }