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 package ti.sysbios.hal;
37
38 import xdc.runtime.Error;
39
40 /*!
41 * ======== Timer ========
42 * Timer Manager Proxy.
43 *
44 * The ti.sysbios.hal.Timer module presents a standard interface for using
45 * the timer peripherals. This module is part of the Hardware Abstraction
46 * Layer (HAL) package, which hides target/device-specific characteristics
47 * of the hardware.
48 *
49 * You can use this module to create a timer (that is, to mark a timer for
50 * use) and configure it to call a tickFxn when the timer expires. Use this
51 * module only if you do not need to do any custom configuration of the
52 * timer peripheral.
53 *
54 * The timer can be configured as a one-shot or a continuous mode timer.
55 * The period can be specified in timer counts or microseconds.
56 *
57 * The timer interrupt always uses the Hwi dispatcher. The Timer tickFxn
58 * runs in the context of a Hwi thread. The Timer module automatically
59 * creates a Hwi instance for the timer interrupt.
60 *
61 * The actual implementations of the Timer module functions are
62 * provided by device/family-specific Timer modules.
63 * Additional, family-specific Timer module APIs may also be provided by
64 * your Timer module implementation.
65 * Follow the link below to determine which Timer implementation is used
66 * for your target:
67 *
68 * {@link ./../family/doc-files/delegates.html Delegate Mappings}
69 *
70 * @a(constraints)
71 * Since the hal Timer module has no knowledge of the delegate Timer
72 * module's instance definition, Timer_construct() can NOT be properly
73 * supported.
74 *
75 * If {@link ti.sysbios.BIOS#runtimeCreatesEnabled BIOS.runtimeCreatesEnabled}
76 * is set to true, both Timer_create() and Timer_construct()
77 * will attempt to dynamically create (ie NOT construct) a delegate Timer
78 * object.
79 *
80 * If {@link ti.sysbios.BIOS#runtimeCreatesEnabled BIOS.runtimeCreatesEnabled}
81 * is set to false, both Timer_create() and Timer_construct() will fail.
82 *
83 * @p(html)
84 * <h3> Calling Context </h3>
85 * <table border="1" cellpadding="3">
86 * <colgroup span="1"></colgroup> <colgroup span="5" align="center">
87 * </colgroup>
88 *
89 * <tr><th> Function </th><th> Hwi </th><th> Swi </th>
90 * <th> Task </th><th> Main </th><th> Startup </th></tr>
91 * <!-- -->
92 * <tr><td> {@link #getNumTimers} </td><td> Y </td>
93 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
94 * <tr><td> {@link #getStatus} </td><td> Y </td>
95 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
96 * <tr><td> {@link #Params_init} </td><td> Y </td>
97 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
98 * <tr><td> {@link #construct} </td><td> Y </td>
99 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
100 * <tr><td> {@link #create} </td><td> N </td>
101 * <td> N </td><td> Y </td><td> Y </td><td> N </td></tr>
102 * <tr><td> {@link #delete} </td><td> N </td>
103 * <td> N </td><td> Y </td><td> Y </td><td> N </td></tr>
104 * <tr><td> {@link #destruct} </td><td> Y </td>
105 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
106 * <tr><td> {@link #getFreq} </td><td> Y </td>
107 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
108 * <tr><td> {@link #getPeriod} </td><td> Y </td>
109 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
110 * <tr><td> {@link #setPeriod} </td><td> Y </td>
111 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
112 * <tr><td> {@link #setPeriodMicroSecs} </td><td> Y </td>
113 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
114 * <tr><td> {@link #start} </td><td> Y </td>
115 * <td> Y </td><td> Y </td><td> N </td><td> N </td></tr>
116 * <tr><td> {@link #stop} </td><td> Y </td>
117 * <td> Y </td><td> Y </td><td> N </td><td> N </td></tr>
118 * <tr><td colspan="6"> Definitions: <br />
119 * <ul>
120 * <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
121 * <li> <b>Swi</b>: API is callable from a Swi thread. </li>
122 * <li> <b>Task</b>: API is callable from a Task thread. </li>
123 * <li> <b>Main</b>: API is callable during any of these phases: </li>
124 * <ul>
125 * <li> In your module startup after this module is started
126 * (e.g. Timer_Module_startupDone() returns TRUE). </li>
127 * <li> During xdc.runtime.Startup.lastFxns. </li>
128 * <li> During main().</li>
129 * <li> During BIOS.startupFxns.</li>
130 * </ul>
131 * <li> <b>Startup</b>: API is callable during any of these phases:</li>
132 * <ul>
133 * <li> During xdc.runtime.Startup.firstFxns.</li>
134 * <li> In your module startup before this module is started
135 * (e.g. Timer_Module_startupDone() returns FALSE).</li>
136 * </ul>
137 * </ul>
138 * </td></tr>
139 *
140 * </table>
141 * @p
142 */
143
144 @ModuleStartup
145
146 module Timer inherits ti.sysbios.interfaces.ITimer
147 {
148 /*!
149 * ======== viewGetHandle ========
150 * @_nodoc
151 * Returns the corresponding hal Timer handle for a delegate Timer handle
152 *
153 * @b(returns) hal Timer handle
154 */
155 metaonly Handle viewGetHandle(Ptr pi);
156
157 instance:
158
159 /*!
160 * ======== create ========
161 * Create a timer.
162 *
163 * Create could fail if timer peripheral is unavailable. To
164 * request any available timer use {@link #ANY} as the id.
165 * TimerId's are logical ids. The family-specific implementations
166 * map the ids to physical peripherals.
167 *
168 * @param(id) Timer id ranging from 0 to a platform specific value
169 * @param(tickFxn) function that runs upon timer expiry.
170 */
171 override create(Int id, FuncPtr tickFxn);
172
173 internal:
174
175 /*! target/device-specific Timer implementation. */
176 proxy TimerProxy inherits ti.sysbios.interfaces.ITimer;
177
178 struct Instance_State {
179 TimerProxy.Handle pi;
180 };
181 }