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