1 /*
2 * Copyright (c) 2014, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /*
33 * ======== Timer.xdc ========
34 *
35 */
36
37 package ti.sysbios.family.arm.cc26xx;
38
39 import xdc.rov.ViewInfo;
40
41 import xdc.runtime.Types;
42 import xdc.runtime.Error;
43
44 import ti.sysbios.interfaces.ITimer;
45 import ti.sysbios.family.arm.m3.Hwi;
46
47 /*!
48 * ======== Timer ========
49 * CC26xx Timer Peripheral Manager
50 *
51 * This module manages the RTC timer available on CC26xx devices.
52 *
53 * The Timer module supports the timer in 'one shot', 'continuous', and
54 * 'dynamic' modes.
55 *
56 * In 'one shot' mode, a timer function will "fire" (run) when the timer
57 * period expires. In 'one shot' mode this will only happen once.
58 *
59 * In 'continuous' mode, the specified timer function will "fire" every
60 * time the period expires, throughout the lifetime of the program.
61 *
62 * In 'dynamic' mode, the specified timer function will "fire" every
63 * time the period expires. But the period of the timer can be changed
64 * dynamically, to correspond to the next tick interrupt needed from the
65 * timer. This mode is used by the SYS/BIOS
66 * {@link ti.sysbios.knl.Clock Clock} module for implementing
67 * dynamic tick suppression, to reduce the number of interrupts from the
68 * timer to the minimum required for currently scheduled timeouts.
69 *
70 * @p(html) 71 * <h3> Calling Context </h3>
72 * <table border="1" cellpadding="3">
73 * <colgroup span="1"></colgroup> <colgroup span="5" align="center">
74 * </colgroup>
75 *
76 * <tr><th> Function </th><th> Hwi </th><th> Swi </th>
77 * <th> Task </th><th> Main </th><th> Startup </th></tr>
78 * <!-- -->
79 * <tr><td> {@link #getNumTimers} </td><td> Y </td>
80 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
81 * <tr><td> {@link #getStatus} </td><td> Y </td>
82 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
83 * <tr><td> {@link #Params_init} </td><td> N </td>
84 * <td> N </td><td> N </td><td> N </td><td> N </td></tr>
85 * <tr><td> {@link #construct} </td><td> N </td>
86 * <td> N </td><td> N </td><td> N </td><td> N </td></tr>
87 * <tr><td> {@link #create} </td><td> N </td>
88 * <td> N </td><td> N </td><td> N </td><td> N </td></tr>
89 * <tr><td> {@link #delete} </td><td> N </td>
90 * <td> N </td><td> N </td><td> N </td><td> N </td></tr>
91 * <tr><td> {@link #destruct} </td><td> N </td>
92 * <td> N </td><td> N </td><td> N </td><td> N </td></tr>
93 * <tr><td> {@link #getCount} </td><td> Y </td>
94 * <td> Y </td><td> Y </td><td> N </td><td> N </td></tr>
95 * <tr><td> {@link #getFreq} </td><td> Y </td>
96 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
97 * <tr><td> {@link #getFunc} </td><td> Y </td>
98 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
99 * <tr><td> {@link #getPeriod} </td><td> Y </td>
100 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
101 * <tr><td> {@link #setFunc} </td><td> Y </td>
102 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
103 * <tr><td> {@link #setPeriod} </td><td> Y </td>
104 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
105 * <tr><td> {@link #setPeriodMicroSecs} </td><td> Y </td>
106 * <td> Y </td><td> Y </td><td> Y </td><td> N </td></tr>
107 * <tr><td> {@link #start} </td><td> Y </td>
108 * <td> Y </td><td> Y </td><td> N </td><td> N </td></tr>
109 * <tr><td> {@link #stop} </td><td> Y </td>
110 * <td> Y </td><td> Y </td><td> N </td><td> N </td></tr>
111 * <tr><td colspan="6"> Definitions: <br />
112 * <ul>
113 * <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
114 * <li> <b>Swi</b>: API is callable from a Swi thread. </li>
115 * <li> <b>Task</b>: API is callable from a Task thread. </li>
116 * <li> <b>Main</b>: API is callable during any of these phases: </li>
117 * <ul>
118 * <li> In your module startup after this module is started
119 * (e.g. Timer_Module_startupDone() returns TRUE). </li>
120 * <li> During xdc.runtime.Startup.lastFxns. </li>
121 * <li> During main().</li>
122 * <li> During BIOS.startupFxns.</li>
123 * </ul>
124 * <li> <b>Startup</b>: API is callable during any of these phases:</li>
125 * <ul>
126 * <li> During xdc.runtime.Startup.firstFxns.</li>
127 * <li> In your module startup before this module is started
128 * (e.g. Timer_Module_startupDone() returns FALSE).</li>
129 * </ul>
130 * </ul>
131 * </td></tr>
132 *
133 * </table>
134 * @p 135 */
136 @ModuleStartup /* To configure static timers */
137 @InstanceInitStatic
138
139 module Timer inherits ti.sysbios.interfaces.ITimer
140 {
141 /*! override supportsDynamic - this Timer does support RunMode_DYNAMIC */
142 overridemetaonlyconfig Bool supportsDynamic = true;
143
144 /*! override defaultMode - use RunMode_PERIODIC by default */
145 overridemetaonlyconfig Bool defaultDynamic = true;
146
147 // -------- Module Types --------
148
149 /*! Max value of Timer period for PeriodType_COUNTS */
150 const UInt MAX_PERIOD = 0xFFFFFFFF;
151
152 /*! @_nodoc 153 * Min instructions to use in trigger().
154 */
155 const Int MIN_SWEEP_PERIOD = 1;
156
157 /*! @_nodoc */
158 @XmlDtd
159 metaonlystruct BasicView {
160 Ptr halTimerHandle;
161 String label;
162 UInt id;
163 String startMode;
164 UInt period;
165 String tickFxn[];
166 UArg arg;
167 String hwiHandle;
168 };
169
170 /*! @_nodoc */
171 metaonlystruct DeviceView {
172 UInt id;
173 String device;
174 String devAddr;
175 UInt intNum;
176 UInt period;
177 UInt64 period64;
178 UInt currCount;
179 UInt remainingCount;
180 UInt64 prevThreshold;
181 UInt64 nextThreshold;
182 String state;
183 };
184
185 /*! @_nodoc */
186 metaonlystruct ModuleView {
187 String availMask;
188 }
189
190 /*! @_nodoc */
191 @Facet
192 metaonlyconfig ViewInfo.Instance rovViewInfo =
193 ViewInfo.create({
194 viewMap: [
195 [
196 'Basic',
197 {
198 type: ViewInfo.INSTANCE,
199 viewInitFxn: 'viewInitBasic',
200 structName: 'BasicView'
201 }
202 ],
203 [
204 'Device',
205 {
206 type: ViewInfo.INSTANCE,
207 viewInitFxn: 'viewInitDevice',
208 structName: 'DeviceView'
209 }
210 ],
211 [
212 'Module',
213 {
214 type: ViewInfo.MODULE,
215 viewInitFxn: 'viewInitModule',
216 structName: 'ModuleView'
217 }
218 ],
219 ]
220 });
221
222 /*!
223 * ======== E_invalidTimer ========
224 * Error raised when specified timer id is not supported
225 */
226 config Error.Id E_invalidTimer = {
227 msg: "E_invalidTimer: Invalid Timer Id %d"
228 };
229
230 /*!
231 * ======== E_notAvailable ========
232 * Error raised when requested timer is in use
233 */
234 config Error.Id E_notAvailable = {
235 msg: "E_notAvailable: Timer not available %d"
236 };
237
238 /*!
239 * ======== E_cannotSupport ========
240 * Error raised when requested period is not supported
241 */
242 config Error.Id E_cannotSupport = {
243 msg: "E_cannotSupport: Timer cannot support requested period %d"
244 };
245
246 /*!
247 * ======== anyMask ========
248 * Mask of available timers
249 *
250 * This mask is used to identify the timers that can be used when
251 * Timer_create() is called with an id equal to
252 * {@link Timer#ANY Timer_ANY}.
253 */
254 config UInt anyMask = 0x1;
255
256 /*!
257 * ======== funcHookCH1 ========
258 * Optional hook function for processing RTC channel 1 events
259 *
260 * Function hooks are only supported with RunMode_DYNAMIC.
261 */
262 config FuncPtr funcHookCH1 = null;
263
264 /*!
265 * ======== funcHookCH2 ========
266 * Optional hook function for processing RTC channel 2 events.
267 *
268 * Function hooks are only supported with RunMode_DYNAMIC.
269 */
270 config FuncPtr funcHookCH2 = null;
271
272 /*!
273 * ======== dynamicStub ========
274 * @_nodoc 275 *
276 * @param(arg) Unused.
277 */
278 Void dynamicStub(UArg arg);
279
280 /*!
281 * ======== dynamicMultiStub ========
282 * @_nodoc 283 *
284 * @param(arg) Unused.
285 */
286 Void dynamicMultiStub(UArg arg);
287
288 /*!
289 * ======== periodicStub ========
290 * @_nodoc 291 *
292 * @param(arg) Unused.
293 */
294 Void periodicStub(UArg arg);
295
296 /*!
297 * ======== getCount64 ========
298 * Read the 64-bit timer counter register
299 *
300 * @b(returns) timer counter value
301 */
302 UInt64 getCount64(Object * timer);
303
304 /*!
305 * ======== getExpiredCounts64 ========
306 * Returns expired counts (64-bits) since the last serviced interrupt.
307 *
308 * @b(returns) timer counter value
309 */
310 UInt64 getExpiredCounts64(Object * timer);
311
312 /*!
313 * ======== getHandle ========
314 * @_nodoc 315 * Used by TimestampProvider module to get hold of timer handle used by
316 * Clock.
317 *
318 * @param(id) timer Id.
319 */
320 Handle getHandle(UInt id);
321
322 instance:
323
324 /*! Hwi Params for Hwi Object. Default is null. */
325 config Hwi.Params *hwiParams = null;
326
327 internal: /* not for client use */
328
329 /*!
330 * ======== noStartupNeeded ========
331 * Flag used to prevent misc code from being brought in
332 * un-necessarily
333 */
334 config UInt startupNeeded = false;
335
336 /*
337 * ======== initDevice ========
338 * reset timer to its resting state
339 */
340 Void initDevice(Object *timer);
341
342 /*
343 * ======== postInit ========
344 * finish initializing static Timers
345 */
346 Int postInit(Object *timer, Error.Block *eb);
347
348 /*
349 * ======== setThreshold ========
350 * set the compare threshold in RTC register
351 */
352 Void setThreshold(Object *timer, UInt32 next, Bool wrap);
353
354 struct Instance_State {
355 Bool staticInst;
356 Int id;
357 ITimer.StartMode startMode;
358 UInt32 period;
359 UArg arg;
360 Hwi.FuncPtr tickFxn;
361 Types.FreqHz frequency;
362 Hwi.Handle hwi;
363 UInt64 period64;
364 UInt64 savedCurrCount;
365 UInt64 prevThreshold;
366 UInt64 nextThreshold;
367 }
368
369 struct Module_State {
370 UInt availMask; /* available peripherals */
371 Handle handle; /* array of handles based on id */
372 }
373 }