1 /*
2 * Copyright (c) 2013, 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 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: /* not for client use */
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 }