1 /*
2 * Copyright (c) 2011, 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 * ======== EventCombiner.xdc ========
34 *
35 *
36 */
37
38 package ti.sysbios.family.c64p;
39
40 import xdc.runtime.Error;
41
42 /*!
43 * ======== EventCombiner ========
44 * Event Combiner Manager module
45 *
46 * The event combiner allows the user to combine up to 32 system events
47 * into a single combined event. The events 0, 1, 2, and 3 are the events
48 * associated with the event combiner. Using the EventCombiner module
49 * along with the Hwi module, allows the user to route a combined event
50 * to any of the 12 maskable CPU interrupts available on GEM. The
51 * EventCombiner supports up to 128 system events. Users can specify
52 * a function and an argument for each system event and can choose to
53 * enable whichever system events they want.
54 *
55 * @p(html) 56 * <h3> Calling Context </h3>
57 * <table border="1" cellpadding="3">
58 * <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
59 *
60 * <tr><th> Function </th><th> Hwi </th><th> Swi </th><th> Task </th><th> Main </th><th> Startup </th></tr>
61 * <!-- -->
62 * <tr><td> {@link #disableEvent} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
63 * <tr><td> {@link #dispatch} </td><td> Y </td><td> N </td><td> N </td><td> N </td><td> N </td></tr>
64 * <tr><td> {@link #dispatchPlug} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
65 * <tr><td> {@link #enableEvent} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
66 * <tr><td colspan="6"> Definitions: <br />
67 * <ul>
68 * <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
69 * <li> <b>Swi</b>: API is callable from a Swi thread. </li>
70 * <li> <b>Task</b>: API is callable from a Task thread. </li>
71 * <li> <b>Main</b>: API is callable during any of these phases: </li>
72 * <ul>
73 * <li> In your module startup after this module is started (e.g. EventCombiner_Module_startupDone() returns TRUE). </li>
74 * <li> During xdc.runtime.Startup.lastFxns. </li>
75 * <li> During main().</li>
76 * <li> During BIOS.startupFxns.</li>
77 * </ul>
78 * <li> <b>Startup</b>: API is callable during any of these phases:</li>
79 * <ul>
80 * <li> During xdc.runtime.Startup.firstFxns.</li>
81 * <li> In your module startup before this module is started (e.g. EventCombiner_Module_startupDone() returns FALSE).</li>
82 * </ul>
83 * </ul>
84 * </td></tr>
85 *
86 * </table>
87 * @p 88 */
89
90 @ModuleStartup
91
92 module EventCombiner
93 {
94 /*!
95 * ======== EventView ========
96 * @_nodoc 97 */
98 metaonlystruct EventView {
99 UInt eventId;
100 String fxn;
101 String arg;
102 };
103
104 /*!
105 * ======== rovViewInfo ========
106 * @_nodoc 107 */
108 @Facet
109 metaonlyconfig xdc.rov.ViewInfo.Instance rovViewInfo =
110 xdc.rov.ViewInfo.create({
111 viewMap: [
112 ['Events',
113 {
114 type: xdc.rov.ViewInfo.MODULE_DATA,
115 viewInitFxn: 'viewInitEvents',
116 structName: 'EventView'
117 }
118 ]
119 ]
120 });
121
122 // -------- Module Constants --------
123
124 /*! C64+ supports 128 events. */
125 const Int NUM_EVENTS = 128;
126
127 // -------- Module Types --------
128
129 /*! Event Combiner dispatcher function type definition. */
130 typedef Void (*FuncPtr)(UArg);
131
132 /*!
133 * Event Configuration Object.
134 *
135 * unmask - Boolean value that specifies if an event should be
136 * unmasked in the C64+ EVTMASK registers.
137 * fxn - function to call when this event occurs.
138 * arg - arg to fxn.
139 */
140 metaonlystruct EventObj {
141 Bool unmask;
142 FuncPtr fxn;
143 UArg arg;
144 };
145
146 /*!
147 * Error raised when an unplug Event is executed.
148 */
149 config Error.Id E_unpluggedEvent = {
150 msg: "E_unpluggedEvent: Event# %d is unplugged"
151 };
152
153 // -------- Module Parameters --------
154
155 /*!
156 * ======== EVTMASK ========
157 * Holds the initialization values for the C64+ EVTMASK registers (0-3).
158 *
159 * It is assigned values based on the 'unmask' member of the 'events'
160 * configuration array. It can also be assigned manually in the program
161 * configuration script.
162 */
163 config Bits32 EVTMASK[4];
164
165 /*!
166 * ======== events ========
167 * For holding configuration values for all C64+ events.
168 *
169 * Array elements can be configured in the program
170 * configuration script.
171 */
172 metaonlyconfig EventObj events[NUM_EVENTS];
173
174 /*!
175 * ======== eventGroupHwiNum ========
176 * Configures the mapping of a C64+ combined event group to an interrupt.
177 *
178 * There is one element per combined event group (0-3).
179 */
180 metaonlyconfig Int eventGroupHwiNum[4];
181
182 /*!
183 * ======== dispatchEventGroup ========
184 * Configuration method for assigning the eventGroupHwiNum array.
185 *
186 * It accomplishes the same thing as directly setting
187 * eventGroupHwiNum[0-3].
188 *
189 */
190 metaonly Void dispatchEventGroup(UInt evt, UInt hwiVec);
191
192 /*!
193 * ======== disableEvent ========
194 * Disables 'evt' from contributing to its combined event group.
195 *
196 * It accomplishes this by setting the corresponding
197 * bit in the C64+ EVTMASK array to 1 (to mask it).
198 */
199 Void disableEvent(UInt evt);
200
201 /*!
202 * ======== enableEvent ========
203 * Enables 'evt' to contribute to its combined event group.
204 *
205 * It accomplishes this by setting the corresponding
206 * bit in the C64+ EVTMASK array to 0 (to unmask it).
207 */
208 Void enableEvent(UInt evt);
209
210 /*!
211 * ======== dispatch ========
212 * The Event Combiner dispatcher.
213 *
214 * It is mostly used internally, but can be used directly by the user.
215 */
216 Void dispatch(UInt evt);
217
218 /*!
219 * ======== dispatchPlug ========
220 * Used to configure a dispatcher entry for 'evt'.
221 *
222 * The parameters correspond to the same ones for static configuration
223 * in EventObj. dispatchPlug does not map the corresponding combined
224 * event group to an Hwi interrupt - such an action needs to be
225 * performed either using the event combiner configuration or using the Hwi
226 * module.
227 */
228 Void dispatchPlug(UInt evt, FuncPtr fxn, UArg arg, Bool unmask);
229
230 /*!
231 * @_nodoc 232 * ======== unused ========
233 * unused exists simply to map a call in the Ecm dispatcher calling
234 * context to the System_exit calling context (casts UArg to Int).
235 */
236 Void unused(UArg arg);
237
238 internal:
239
240 struct DispatchTabElem {
241 FuncPtr fxn;
242 UArg arg;
243 };
244
245 struct Module_State {
246 DispatchTabElem dispatchTab[NUM_EVENTS];
247 };
248
249 }
250
251 /*
252 * @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,453; 1-20-2011 12:27:52; /db/vtree/library/trees/avala/avala-o26x/src/ xlibrary
253 254 */
255