1 /*
2 * Copyright (c) 2008 Texas Instruments. All rights reserved.
3 * This program and the accompanying materials are made available under the
4 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License
5 * v. 1.0 which accompanies this distribution. The Eclipse Public License is
6 * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
7 * Distribution License is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * Contributors:
11 * Texas Instruments - initial implementation
12 * */
13 /*
14 * ======== Startup.xdc ========
15 */
16
17 package xdc.runtime;
18
19 /*!
20 * ======== Startup ========
21 * The `xdc.runtime` startup bootstrap
22 *
23 * This module manages the very early startup initialization that occurs
24 * before C's `main()` function is invoked. This initialization typically
25 * consists of setting hardware specific registers that control watchdog
26 * timers, access to memory, cache settings, clock speeds, etc.
27 *
28 * In addition to configuration parameters that allow the user to add custom
29 * startup functions, this module also provides services that allow modules
30 * to automatically add initialiazation functions to the startup sequence.
31 *
32 * @a(Startup Sequence) 33 * The following list defines the startup sequence and, in particular, when
34 * user provided startup functions are invoked:
35 * @p(nlist) 36 * - CPU is initialized and initial C stack setup is performed.
37 * - The function specified by `Startup.resetFxn` is called.
38 * `Startup.resetFxn` is called only on platforms where reset is performed
39 * before running a program. For example, boot code for all TI targets
40 * invokes `Startup.resetFxn`, but this function is not invoked on
41 * Microsoft targets.
42 * - C runtime initialization is performed.
43 * - Functions from the array `Startup.firstFxns` are called.
44 * - All `Mod_Module_startup` functions (see Module Initialization below)
45 * are called in a loop until all such functions return
46 * `{@link #Startup_DONE}` or the `{@link #maxPasses}` threshold is
47 * reached.
48 * - Functions from the array `Startup.lastFxns` are called.
49 * - The function `main` is called.
50 * @p 51 * The steps 4 - 6 occur during C++ static object initialization. Since
52 * the ANSI C++ Language Standard does not provide a means to control
53 * the order of C++ constructors, if a C++ constructor uses an XDC module,
54 * there is no guarantee that the module's startup function already ran.
55 * Therefore, any C++ constructor that needs XDC modules' services should
56 * call `Startup_exec` first to force all startup related functions from
57 * steps 4 - 6 to run, before the constructor uses any XDC module.
58 * @p 59 * Also, if a target does not support C++, the steps 4 - 6 will not run
60 * automatically. It is then up to a user's code to invoke `Startup_exec`,
61 * possibly as the first step in `main`.
62 * @p 63 *
64 * @a(Module Initialization) 65 * Every module can optionally define a startup function which is called
66 * before `main()`. Modules declare that they want to participate in this
67 * startup sequence via the `@ModuleStartup` attribute in the module's spec
68 * file. Modules that use this attribute must also implement the following
69 * startup function:
70 * @p(code) 71 * Int Mod_Module_startup(Int state);
72 * @p 73 * where "Mod" is the name of the module requesting startup support.
74 *
75 * The parameter to the startup function serves as "state variable" whose
76 * initial value will be `Startup_NOTDONE`. If `startup()` returns a value
77 * other than `Startup_DONE`, it will be called in a subsequent pass with this
78 * return value passed in as `state`. To ensure this process terminates,
79 * no startup function is ever called more than `{@link #maxPasses}`
80 * times.
81 *
82 * For situations in which the startup of one module depends upon another
83 * having completed its startup processing, the following function is
84 * automatically defined for all modules and proxies:
85 * @p(code) 86 * Bool Mod_Module_startupDone();
87 * @p 88 * where "Mod" is the name of some module or proxy. These predicates can
89 * be used as guards inside of a startup function to probe whether a
90 * particular module has completed its own startup processing. As a
91 * convenience, the function `Startup_rtsDone()` probes the necessary set of
92 * `xdc.runtime` modules required to support instance `create()` functions, and
93 * should be called before any startup-time instance creation and/or
94 * memory allocation is performed.
95 * @p(code) 96 * Int Mod_Module_startup(Int state)
97 * {
98 * if (!Startup_rtsDone()) {
99 * return (Startup_NOTDONE);
100 * }
101 * .
102 * .
103 * .
104 * return (Startup_DONE);
105 * }
106 * @p 107 *
108 */
109 @Template("./Startup.xdt")
110
111 module Startup {
112
113 /*!
114 * ======== DONE ========
115 * Returned from module startup functions no further calls are required
116 */
117 const Int DONE = -1;
118
119 /*!
120 * ======== NOTDONE ========
121 * Initial value of state argument passed to module startup functions
122 */
123 const Int NOTDONE = 0;
124
125 /*!
126 * ======== ModuleView ========
127 * @_nodoc 128 */
129 metaonlystruct ModuleView {
130 Bool rtsStartupDone;
131 Bool startupBegun;
132 String resetFxn;
133 String firstFxns[];
134 String lastFxns[];
135 }
136
137 /*!
138 * ======== StartupStateView ========
139 * @_nodoc 140 */
141 metaonlystruct StartupStateView {
142 Int order;
143 String moduleName;
144 String done;
145 }
146
147 /*!
148 * ======== rovViewInfo ========
149 * @_nodoc 150 */
151 @Facet
152 metaonlyconfig xdc.rov.ViewInfo.Instance rovViewInfo =
153 xdc.rov.ViewInfo.create({
154 viewMap: [
155 ['Module',
156 {
157 type: xdc.rov.ViewInfo.MODULE,
158 viewInitFxn: 'viewInitModule',
159 structName: 'ModuleView'
160 }
161 ],
162 ['Startup State',
163 {
164 type: xdc.rov.ViewInfo.MODULE_DATA,
165 viewInitFxn: 'viewInitStartupState',
166 structName: 'StartupStateView'
167 }
168 ]
169 ]
170 });
171
172 /*!
173 * ======== maxPasses ========
174 * Max number of iterations over the set of startup functions
175 */
176 config Int maxPasses = 32;
177
178 /*!
179 * ======== InitFxn ========
180 * Type of function assignable to `firstFxns`, `lastFxns`, or `resetFxn`
181 */
182 typedef Void (*InitFxn)();
183
184 /*!
185 * ======== firstFxns ========
186 * List of functions called before module startup
187 *
188 */
189 config InitFxn firstFxns[length] = [];
190
191 /*!
192 * ======== lastFxns ========
193 * List of functions called after module startup
194 *
195 */
196 config InitFxn lastFxns[length] = [];
197
198 /*!
199 * ======== resetFxn ========
200 * Function to be called by during initialization
201 *
202 * This function is called only on platforms where reset is performed
203 * before running the program. The purpose of this function is to set up
204 * the hardware registers (cache, external memory interface, etc.) before
205 * any other code executes.
206 *
207 */
208 metaonlyconfig InitFxn resetFxn = null;
209
210 /*!
211 * ======== exec ========
212 * Execute the startup functions of all resident modules
213 *
214 * Note that this function is idempotent, and can be called at any point
215 * in the platform/target startup sequence in which "ordinary" C functions
216 * can execute. By default, this function is called as part of the
217 * standard C++ static initialization sequence.
218 *
219 * If your target compiler does not support C++, this function must be
220 * called at least once prior to using any `xdc.runtime` modules.
221 * Simply call this function at the very beginning of `main()`.
222 */
223 Void exec();
224
225 /*!
226 * ======== rtsDone ========
227 * Query the state of the `xdc.runtime` package
228 *
229 * This function is used by module startup functions to determine
230 * when it is possible to use the `xdc.runtime` modules; e.g. to
231 * allocate memory, create instances managed by some module (even
232 * those outside the `xdc.runtime` package), call a `Log` function,
233 * etc.
234 *
235 * @a(returns) 236 * Returns `TRUE` when all `xdc.runtime` modules have completed
237 * initialization.
238 */
239 Bool rtsDone();
240
241 internal:
242
243 /*!
244 * ======== reset ========
245 * Application-specific reset function
246 *
247 * This function is defined in `Startup.xdt`
248 * (`xdc_runtime_Startup_reset__I`) and is called as early as
249 * possible in the program initialization process; for many platforms,
250 * it is called prior the the initialization of the C runtime
251 * environment.
252 */
253 Void reset();
254
255 Void startMods(Int state[], Int len);
256 readonlyconfig Void (*startModsFxn)(Int[], Int) = startMods;
257
258 extern Void execImplFxn() = xdc_runtime_Startup_exec__I;
259
260 readonlyconfig Void (*execImpl)() = execImplFxn;
261
262 typedef Int (*SFxn)(Int);
263 config SFxn sfxnTab[];
264
265 /*!
266 * ======== sfxnRts ========
267 * Array of runtime modules' startup functions
268 *
269 * This array also contains startup functions of the modules that inherit
270 * from interfaces in `xdc.runtime`. Functions added to this array are
271 * called only once before the startup procedure for all modules begins.
272 */
273 config Bool sfxnRts[];
274
275 struct Module_State {
276 Int *stateTab; /* initially null */
277 Bool execFlag; /* if true, startup code processing started */
278 Bool rtsDoneFlag;
279 };
280
281 }
282 /*
283 * @(#) xdc.runtime; 2, 1, 0,384; 9-3-2012 16:22:19; /db/ztree/library/trees/xdc/xdc-y35x/src/packages/
284 */
285