1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 34 35
36
37 package ti.sysbios;
38
39 import xdc.rov.ViewInfo;
40
41 import xdc.runtime.Error;
42 import xdc.runtime.Types;
43
44 /*! ======== BIOS ========
45 * SYS/BIOS Top-Level Manager
46 *
47 * This module is responsible for setting up global parameters
48 * pertaining to SYS/BIOS and for performing the SYS/BIOS startup
49 * sequence.
50 *
51 * SYS/BIOS configures the
52 * {@link xdc.runtime.Memory#defaultHeapInstance Memory.defaultHeapInstance}
53 * using a {@link ti.sysbios.heaps.HeapMem HeapMem} instance of size
54 * {@link #heapSize}.
55 *
56 * The SYS/BIOS startup sequence is logically divided into two phases: those
57 * operations that occur prior to the application's "main()" function being
58 * called, and those operations that are performed after the application's
59 * "main()" function is invoked.
60 *
61 * The "before main()" startup sequence is governed completely by the RTSC
62 * runtime package's {@link xdc.runtime.Startup Startup} module.
63 *
64 * The "after main()" startup sequence is governed by SYS/BIOS and is
65 * initiated by an explicit call to the {@link #start BIOS_start()} function
66 * at the end of the application's main() function.
67 *
68 * Control points are provided at various places in each of the two startup
69 * sequences for user startup operations to be inserted.
70 *
71 * The RTSC runtime startup sequence is as follows:
72 *
73 * @p(nlist)
74 * - Immediately after CPU reset, perform target-specific CPU
75 * initialization (beginning at c_int00).
76 * - Prior to cinit(), run the user-supplied "reset functions"
77 * (see {@link xdc.runtime.Reset#fxns Reset.fxns}).
78 * - Run cinit() to initialize C runtime environment.
79 * - Run the user-supplied "first functions"
80 * (see {@link xdc.runtime.Startup#firstFxns Startup.firstFxns}).
81 * - Run all the module initialization functions.
82 * - Run pinit().
83 * - Run the user-supplied "last functions"
84 * (see {@link xdc.runtime.Startup#lastFxns Startup.lastFxns}).
85 * - Run main().
86 * @p
87 *
88 * The SYS/BIOS startup sequence begins at the end of main() when
89 * BIOS_start() is called:
90 *
91 * @p(nlist)
92 * - Run the user-supplied "startup functions"
93 * (see {@link #startupFxns BIOS.startupFxns}).
94 * - Enable Hardware Interrupts.
95 * - Enable Software Interrupts. If the system supports Software Interrupts
96 * (Swis) (see {@link #swiEnabled BIOS.swiEnabled}), then the SYS/BIOS
97 * startup sequence enables Swis at this point.
98 * - Timer Startup. If the system supports Timers, then at this point all
99 * statically configured timers are initialized per their
100 * user-configuration.
101 * If a timer was configured to start "automatically", it is started here.
102 * - Task Startup. If the system supports Tasks
103 * (see {@link #taskEnabled BIOS.taskEnabled}),
104 * then task scheduling begins here. If there are no statically or
105 * dynamically created Tasks in the system, then execution proceeds
106 * directly to the Idle loop.
107 * @p
108 *
109 * @a(Note)
110 * Local variables defined in main() no longer exist once BIOS_start() is
111 * called. The RAM where main's local variables reside is reassigned for
112 * use as the interrupt stack during the execution of BIOS_start().
113 *
114 * Below is a configuration script excerpt that installs a user-supplied
115 * startup function at every possible control point in the RTSC and
116 * SYS/BIOS startup
117 * sequence:
118 *
119 * @p(code)
120 * // get handle to xdc Startup module
121 * var Startup = xdc.useModule('xdc.runtime.Startup');
122 *
123 * // install "reset function"
124 * Startup.resetFxn = '&myReset';
125 *
126 * // install a "first function"
127 * var len = Startup.firstFxns.length
128 * Startup.firstFxns.length++;
129 * Startup.firstFxns[len] = '&myFirst';
130 *
131 * // install a "last function"
132 * var len = Startup.lastFxns.length
133 * Startup.lastFxns.length++;
134 * Startup.lastFxns[len] = '&myLast';
135 *
136 * // get handle to SYS/BIOS module
137 * var BIOS = xdc.useModule('ti.sysbios.BIOS');
138 *
139 * // install a SYS/BIOS startup function
140 * BIOS.addUserStartupFunction('&myBiosStartup');
141 * @p
142 *
143 * @p(html)
144 * <h3> Calling Context </h3>
145 * <table border="1" cellpadding="3">
146 * <colgroup span="1"></colgroup> <colgroup span="5" align="center">
147 * </colgroup>
148 *
149 * <tr><th> Function </th><th> Hwi </th><th> Swi </th>
150 * <th> Task </th><th> Main </th><th> Startup </th></tr>
151 * <!-- -->
152 * <tr><td> {@link #getCpuFreq} </td><td> Y </td><td> Y </td>
153 * <td> Y </td><td> Y </td><td> Y </td></tr>
154 * <tr><td> {@link #getThreadType} </td><td> Y </td><td> Y </td>
155 * <td> Y </td><td> Y </td><td> N </td></tr>
156 * <tr><td> {@link #setCpuFreq} </td><td> Y </td><td> Y </td>
157 * <td> Y </td><td> Y </td><td> Y </td></tr>
158 * <tr><td> {@link #start} </td><td> N </td><td> N </td>
159 * <td> N </td><td> Y </td><td> N </td></tr>
160 * <tr><td colspan="6"> Definitions: <br />
161 * <ul>
162 * <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
163 * <li> <b>Swi</b>: API is callable from a Swi thread. </li>
164 * <li> <b>Task</b>: API is callable from a Task thread. </li>
165 * <li> <b>Main</b>: API is callable during any of these phases: </li>
166 * <ul>
167 * <li> In your module startup after this module is started
168 * (e.g. BIOS_Module_startupDone() returns TRUE). </li>
169 * <li> During xdc.runtime.Startup.lastFxns. </li>
170 * <li> During main().</li>
171 * <li> During BIOS.startupFxns.</li>
172 * </ul>
173 * <li> <b>Startup</b>: API is callable during any of these phases:</li>
174 * <ul>
175 * <li> During xdc.runtime.Startup.firstFxns.</li>
176 * <li> In your module startup before this module is started
177 * (e.g. BIOS_Module_startupDone() returns FALSE).</li>
178 * </ul>
179 * </ul>
180 * </td></tr>
181 *
182 * </table>
183 * @p
184 */
185
186 @CustomHeader
187 @Template("./BIOS.xdt")
188
189 @DirectCall
190 module BIOS
191 {
192 /*!
193 * ======== ThreadType ========
194 * Current thread type definitions
195 *
196 * These values are returned by {@link #getThreadType BIOS_getThreadType}.
197 *
198 * @see #getThreadType
199 */
200 enum ThreadType {
201 ThreadType_Hwi, /*! Current thread is a Hwi */
202 ThreadType_Swi, /*! Current thread is a Swi */
203 ThreadType_Task, /*! Current thread is a Task */
204 ThreadType_Main /*! Current thread is Boot/Main */
205 };
206
207 /*!
208 * ======== RtsLockType ========
209 * Type of Gate to use in the TI RTS library
210 *
211 * @field(NoLocking) no gate is added to the RTS library. In this case,
212 * the application needs to be careful to always serialize access to the
213 * inherently non-reentrant ANSI C functions (such as `malloc()`,
214 * `printf()`, etc.).
215 *
216 * @field(GateHwi) Interrupts are disabled and restored to maintain
217 * re-entrancy. This is a very efficient lock but will also result in
218 * unbounded interrupt latency times. If real-time responce to interrupts
219 * is important, you should not use this gate to lock the RTS library.
220 *
221 * @field(GateSwi) Swis are disabled and restored to maintain
222 * re-entrancy.
223 *
224 * @field(GateMutex) A single mutex is used to maintain re-entrancy.
225 *
226 * @field(GateMutexPri) A single priority inheriting mutex is used to
227 * maintain re-entrancy.
228 *
229 * @see #rtsGateType
230 */
231 enum RtsLockType {
232 NoLocking,
233 GateHwi,
234 GateSwi,
235 GateMutex,
236 GateMutexPri
237 };
238
239 /*!
240 * ======== LibType ========
241 * SYS/BIOS library selection options
242 *
243 * This enumeration defines all the SYS/BIOS library types
244 * provided by the product. You can select the library type by setting
245 * the {@link #libType BIOS.libType} configuration parameter.
246 *
247 * @field(LibType_Instrumented) The library supplied is prebuilt with
248 * logging and assertions enabled.
249 *
250 * @field(LibType_NonInstrumented) The library supplied is prebuilt
251 * with logging and assertions disabled.
252 *
253 * @field(LibType_Custom) This option builds the
254 * SYS/BIOS library from sources using the options specified by
255 * {@link #customCCOpts}. Only the modules and APIs that your application
256 * needs to access are contained in the resulting executable. Program
257 * optimization is performed to reduce the size of the executable and improve
258 * its performance. Enough debug information is retained to allow you to
259 * step through the application code in CCS and locate global variables.
260 *
261 * @field(LibType_Debug) This option is similar to the LibType_Custom option
262 * in that it builds the SYS/BIOS library from sources and omits modules and
263 * APIs that your code does not use. However, no program
264 * optimization is performed. The resulting executable is fully debuggable,
265 * and you can step into SYS/BIOS code. The tradeoff is that the executable
266 * is larger and runs slower than builds that use the LibType_Custom option.
267 *
268 * @see #libType
269 */
270 enum LibType {
271 LibType_Instrumented, /*! Instrumented */
272 LibType_NonInstrumented, /*! Non-instrumented */
273 LibType_Custom, /*! Custom (Optimized) */
274 LibType_Debug /*! Custom (Debug) */
275 };
276
277 /*! Used in APIs that take a timeout to specify wait forever */
278 const UInt WAIT_FOREVER = ~(0);
279
280 /*! Used in APIs that take a timeout to specify no waiting */
281 const UInt NO_WAIT = 0;
282
283 /*! User startup function type definition. */
284 typedef Void (*StartupFuncPtr)(Void);
285
286 /*!
287 * ======== ModuleView ========
288 * @_nodoc
289 */
290 metaonly struct ModuleView {
291 String currentThreadType[];
292 String rtsGateType;
293 Int cpuFreqLow;
294 Int cpuFreqHigh;
295 Bool clockEnabled;
296 Bool swiEnabled;
297 Bool taskEnabled;
298 String startFunc;
299 }
300
301 /*!
302 * ======== ErrorView ========
303 * @_nodoc
304 */
305 metaonly struct ErrorView {
306 String mod;
307 String tab;
308 String inst;
309 String field;
310 String message;
311 }
312
313 /*!
314 * ======== rovViewInfo ========
315 * @_nodoc
316 */
317 @Facet
318 metaonly config ViewInfo.Instance rovViewInfo =
319 ViewInfo.create({
320 viewMap: [
321 [
322 'Module',
323 {
324 type: ViewInfo.MODULE,
325 viewInitFxn: 'viewInitModule',
326 structName: 'ModuleView'
327 }
328 ],
329 [
330 'Scan for errors...',
331 {
332 type: ViewInfo.MODULE_DATA,
333 viewInitFxn: 'viewInitErrorScan',
334 structName: 'ErrorView'
335 }
336 ],
337 ]
338 });
339
340 /*!
341 * ======== libType ========
342 * SYS/BIOS Library type
343 *
344 * The SYS/BIOS runtime is provided in the form of a library that is
345 * linked with your application. Several forms of this library are
346 * provided with the SYS/BIOS product. In addition, there is an
347 * option to build the library from source. This configuration parameter
348 * allows you to select the form of the SYS/BIOS library to use.
349 *
350 * The default value of libType is
351 * {@link #LibType_Instrumented BIOS_LibType_Instrumented}. For a
352 * complete list of options and what they offer see {@link #LibType}.
353 */
354 metaonly config LibType libType = LibType_Instrumented;
355
356 /*!
357 * ======== customCCOpts ========
358 * Compiler options used when building a custom SYS/BIOS library
359 *
360 * When {@link #libType BIOS.libType} is set to
361 * {@link #LibType_Custom BIOS_LibType_Custom} or
362 * {@link #LibType_Debug BIOS_LibType_Debug},
363 * this string contains the options passed to the compiler during any
364 * re-build of the SYS/BIOS sources.
365 *
366 * In addition to the options
367 * specified by `BIOS.customCCOpts`, several `-D` and `-I` options are also
368 * passed to the compiler. The options specified by `BIOS.customCCOpts` are,
369 * however, the first options passed to the compiler on the command line.
370 *
371 * To view the custom compiler options, add the following line to your
372 * config script:
373 *
374 * @p(code)
375 * print(BIOS.customCCOpts);
376 * @p
377 *
378 * When {@link #libType BIOS.libType} is set to
379 * {@link #LibType_Custom BIOS_LibType_Custom},
380 * `BIOS.customCCOpts` is initialized to settings that create a highly
381 * optimized SYS/BIOS library.
382 *
383 * When {@link #libType BIOS.libType} is set to
384 * {@link #LibType_Debug BIOS_LibType_Debug},
385 * `BIOS.customCCOpts` is initialized to settings that create a non-optimized
386 * SYS/BIOS library that can be used to single-step through the APIs with
387 * the CCS debugger.
388 *
389 * More information about using `BIOS.customCCOpts` is provided in the
390 * {@link https://processors.wiki.ti.com/index.php/SYS/BIOS_FAQs SYS/BIOS FAQs}.
391 *
392 * @a(Warning)
393 * The default value of `BIOS.customCCOpts`, which is derived from the target
394 * specified by your configuration, includes runtime model options
395 * (such as endianess) that must be the same for all sources built and
396 * linked into your application. You must not change or add any options
397 * that can alter the runtime model specified by the default value of
398 * `BIOS.customCCOpts`.
399 */
400 metaonly config String customCCOpts;
401
402 /*!
403 * ======== smpEnabled ========
404 * Enables multi core SMP task scheduling
405 *
406 * Currently, this functionality is only supported on the dual core
407 * Cortex M3/M4 Ducati/Benelli subsystems embedded in several TI
408 * SOC devices.
409 *
410 * More information about SMP/BIOS is provided here:
411 * {@link https://processors.wiki.ti.com/index.php/SMP/BIOS SMP/BIOS}.
412 */
413 config Bool smpEnabled = false;
414
415 /*!
416 * ======== cpuFreq ========
417 * CPU frequency in Hz
418 *
419 * This configuration parameter allow SYS/BIOS to convert various
420 * periods between timer ticks (or instruction cycles) and real-time
421 * units. For example, timer periods expressed in micro-seconds need
422 * to be converted into timer ticks in order to properly program the
423 * timers.
424 *
425 * The default value of this parameter is obtained from the platform
426 * (the clockRate property of {@link xdc.cfg.Program#cpu Program.cpu})
427 * which is the CPU clock rate when the processor is reset.
428 *
429 * @a(Example)
430 * If CPU frequency is 720MHz, the following configuration script
431 * configures SYS/BIOS with the proper clock frequency:
432 * @p(code)
433 * var BIOS = xdc.useModule('ti.sysbios.BIOS');
434 * BIOS.cpuFreq.hi = 0;
435 * BIOS.cpuFreq.lo = 720000000;
436 * @p
437 */
438 config Types.FreqHz cpuFreq;
439
440 /*!
441 * ======== runtimeCreatesEnabled ========
442 * Runtime instance creation enable flag.
443 *
444 * true = Mod_create() & Mod_delete() callable at runtime
445 * false = Mod_create() & Mod_delete() not callable at runtime
446 */
447 config Bool runtimeCreatesEnabled = true;
448
449 /*!
450 * ======== taskEnabled ========
451 * SYS/BIOS Task services enable flag
452 *
453 * The following behaviors occur when {@link #taskEnabled} is
454 * set to false:
455 *
456 * @p(blist)
457 * - Static {@link ti.sysbios.knl.Task Task} creation will
458 * result in a fatal build error.
459 * - The Idle task object is not created.
460 * (The Idle functions are invoked within the {@link #start()}
461 * thread.)
462 * - Runtime calls to Task_create will trigger an assertion violation
463 * via {@link xdc.runtime.Assert#isTrue}.
464 * @p
465 */
466 config Bool taskEnabled = true;
467
468 /*!
469 * ======== swiEnabled ========
470 * SYS/BIOS Swi services enable flag
471 *
472 * The following behaviors occur when {@link #swiEnabled} is
473 * set to false:
474 *
475 * @p(blist)
476 * - Static {@link ti.sysbios.knl.Swi Swi} creation will
477 * result in a fatal build error.
478 * - See other effects as noted for {@link #clockEnabled} = false;
479 * - Runtime calls to Swi_create will trigger an assertion violation
480 * via {@link xdc.runtime.Assert#isTrue}.
481 * @p
482 */
483 config Bool swiEnabled = true;
484
485 /*!
486 * ======== clockEnabled ========
487 * SYS/BIOS Clock services enable flag
488 *
489 * The following behaviors occur when {@link #clockEnabled} is
490 * set to false:
491 *
492 * @p(blist)
493 * - Static Clock creation will result in a fatal build error.
494 * - No Clock Swi is created.
495 * - The {@link ti.sysbios.knl.Clock#tickSource Clock_tickSource}
496 * is set to
497 * {@link ti.sysbios.knl.Clock#TickSource_NULL Clock_TickSource_NULL}
498 * to prevent a Timer object from being created.
499 * - For APIs that take a timeout, values other than {@link #NO_WAIT}
500 * will be equivalent to {@link #WAIT_FOREVER}.
501 * @p
502 */
503 config Bool clockEnabled = true;
504
505 /*!
506 * ======== assertsEnabled ========
507 * SYS/BIOS Assert checking in Custom SYS/BIOS library enable flag
508 *
509 * When set to true, Assert checking code is compiled into
510 * the custom library created when {@link #libType BIOS.libType}
511 * is set to {@link #LibType_Custom BIOS_LibType_Custom} or
512 * {@link #LibType_Debug BIOS_LibType_Debug}.
513 *
514 * When set to false, Assert checking code is removed from
515 * the custom library created when BIOS.libType is set to BIOS.LibType_Custom
516 * or BIOS.LibType_Debug.
517 * This option can considerably improve runtime performance as well
518 * significantly reduce the application's code size.
519 *
520 * see {@link #libType BIOS.libType}.
521 */
522 metaonly config Bool assertsEnabled = true;
523
524 /*!
525 * ======== logsEnabled ========
526 * SYS/BIOS Log support in Custom SYS/BIOS library enable flag
527 *
528 * When set to true, SYS/BIOS execution Log code is compiled into
529 * the custom library created when {@link #libType BIOS.libType}
530 * is set to {@link #LibType_Custom BIOS_LibType_Custom} or
531 * {@link #LibType_Debug BIOS_LibType_Debug}.
532 *
533 * When set to false, all Log code is removed from
534 * the custom library created when BIOS.libType = BIOS.LibType_Custom
535 * or BIOS.LibType_Debug.
536 * This option can considerably improve runtime performance as well
537 * signficantly reduce the application's code size.
538 *
539 * see {@link #libType BIOS.libType}.
540 */
541 metaonly config Bool logsEnabled = true;
542
543 /*!
544 * ======== heapSize ========
545 * Size of system heap, units are in MAUs
546 *
547 * The system heap is, by default, used to allocate instance object
548 * state structures, such as {@link ti.sysbios.knl.Task Task} objects
549 * and their stacks, {@link ti.sysbios.knl.Semaphore Semaphore} objects,
550 * etc.
551 *
552 * If the application configuration does not set
553 * Memory.defaultHeapInstance, then SYS/BIOS will create a
554 * {@link ti.sysbios.heaps.HeapMem HeapMem} heap of this size. This
555 * heap will be assigned to
556 * {@link xdc.runtime.Memory#defaultHeapInstance Memory.defaultHeapInstance}
557 * and will therefore be used as the default system heap. This heap
558 * will also be used by the SYS/BIOS version of the standard C library
559 * functions malloc(), calloc() and free().
560 */
561 config SizeT heapSize = 0x1000;
562
563 /*!
564 * ======== heapSection ========
565 * Section to place the system heap
566 *
567 * This configuration parameter allows you to specify a named output
568 * section that will contain the SYS/BIOS system heap. The system heap
569 * is, by default, used to allocate {@link ti.sysbios.knl.Task Task}
570 * stacks and instance object state structures. So, giving this section
571 * a name and explicitly placing it via a linker command file can
572 * significantly improve system performance.
573 *
574 * If heapSection is `null` (or `undefined`) the system heap is placed
575 * in the target's default data section.
576 */
577 config String heapSection = null;
578
579 /*!
580 * ======== heapTrackEnabled ========
581 * Use HeapTrack with system default heap
582 *
583 * This configuration parameter will add a HeapTrack instance on top of
584 * the system heap. HeapTrack adds a tracker packet to every allocated
585 * buffer and displays the information in RTOS Object Viewer (ROV).
586 * An assert will be raised on a free if there was a buffer overflow.
587 */
588 config Bool heapTrackEnabled = false;
589
590 /*!
591 * ======== useSK ========
592 * @_nodoc
593 * use the secure version of BIOS
594 *
595 * This is available for some C66 secure devices only.
596 * This parameter can only be used with the custom build.
597 */
598 config Bool useSK = false;
599
600 /*!
601 * ======== rtsGateType ========
602 * Gate to make sure TI RTS library APIs are re-entrant
603 *
604 * The application gets to determine the type of gate (lock) that is used
605 * in the TI RTS library. The gate will be used to guarantee re-entrancy
606 * of the RTS APIs.
607 *
608 * The type of gate depends on the type of threads that are going to
609 * be calling into the RTS library. For example, if both Swi and Task
610 * threads are going to be calling the RTS library's printf, GateSwi
611 * should be used. In this case, Hwi threads are not impacted (i.e.
612 * disabled) during the printf calls from the Swi or Task threads.
613 *
614 * If NoLocking is used, the RTS lock is not plugged and re-entrancy for
615 * the TI RTS library calls are not guaranteed. The application can plug
616 * the RTS locks directly if it wants.
617 *
618 * Numerous gate types are provided by SYS/BIOS. Each has its advantages
619 * and disadvantages. The following list summarizes when each type is
620 * appropriate for protecting an underlying non-reentrant RTS library.
621 * @p(dlist)
622 * - {@link #GateHwi}:
623 * Interrupts are disabled and restored to maintain re-entrancy.
624 * Use if only making RTS calls from a Hwi, Swi and/or Task.
625 *
626 * - {@link #GateSwi}:
627 * Swis are disabled and restored to maintain re-entrancy. Use if
628 * only making RTS calls from a Swi and/or Task.
629 *
630 * - {@link #GateMutex}:
631 * A single mutex is used to maintain re-entrancy. Use if only
632 * making RTS calls from a Task. Blocks only Tasks that are
633 * also trying to execute critical regions of RTS library.
634 *
635 * - {@link #GateMutexPri}:
636 * A priority inheriting mutex is used to maintain re-entrancy.
637 * Blocks only Tasks that are also trying to execute critical
638 * regions of RTS library. Raises the priority of the Task that
639 * is executing the critical region in the RTS library to the
640 * level of the highest priority Task that is block by the mutex.
641 * @p
642 *
643 * The default value of rtsGateType depends on the type of threading
644 * model enabled by other configuration parameters.
645 * If {@link #taskEnabled} is true, {@link #GateMutex} is used.
646 * If {@link #swiEnabled} is true and {@link #taskEnabled} is false:
647 * {@link #GateSwi} is used.
648 * If both {@link #swiEnabled} and {@link #taskEnabled} are false:
649 * {@link xdc.runtime#GateNull} is used.
650 *
651 * If {@link #taskEnabled} is false, the user should not select
652 * {@link #GateMutex} (or other Task level gates). Similarly, if
653 * {@link #taskEnabled} and {@link #swiEnabled}are false, the user
654 * should not select {@link #GateSwi} or the Task level gates.
655 */
656 metaonly config RtsLockType rtsGateType;
657
658 /*!
659 * ======== startupFxns ========
660 * Functions to be executed at the beginning of BIOS_start()
661 *
662 * These user (or middleware) functions are executed before Hwis,
663 * Swis, and Tasks are started.
664 */
665 metaonly config StartupFuncPtr startupFxns[] = [];
666
667 /*!
668 * ======== addUserStartupFunction ========
669 * @_nodoc
670 * Statically add a function to the startupFxns table.
671 */
672 metaonly Void addUserStartupFunction(StartupFuncPtr func);
673
674 /*!
675 * ======== start ========
676 * Start SYS/BIOS
677 *
678 * The user's main() function is required to call this function
679 * after all other user initializations have been performed.
680 *
681 * This function does not return.
682 *
683 * This function performs any remaining SYS/BIOS initializations
684 * and then transfers control to the highest priority ready
685 * task if {@link #taskEnabled} is true. If {@link #taskEnabled}
686 * is false, control is transferred directly to the Idle Loop.
687 *
688 * The SYS/BIOS start sequence is as follows:
689 * @p(blist)
690 * - Invoke all the functions in the {@link #startupFxns} array.
691 * - call {@link ti.sysbios.hal.Hwi#enable Hwi_startup()}
692 * to enable interrupts.
693 * - if {@link #swiEnabled} is true, call
694 * {@link ti.sysbios.knl.Swi#enable Swi_startup()} to enable
695 * the Swi scheduler.
696 * - Start any statically created or constructed Timers
697 * in the {@link ti.sysbios.hal.Timer#StartMode Timer_StartMode_AUTO}
698 * mode.
699 * - if {@link #taskEnabled} is true, enable the Task scheduler
700 * and transfer the execution thread to the highest priority
701 * task in the {@link ti.sysbios.knl.Task#Mode Task_Mode_READY}
702 * mode.
703 * - Otherwise, fall directly into the Idle Loop.
704 * @p
705 *
706 */
707 Void start();
708
709 /*!
710 * ======== exit ========
711 * Exit currently running SYS/BIOS executable
712 *
713 * This function is called when a SYS/BIOS executable needs to terminate
714 * normally. This function sets the internal SYS/BIOS threadType to
715 * {@link #ThreadType_Main} and then calls
716 * {@link xdc.runtime.System#exit System_exit}(stat), passing along
717 * the 'stat' argument.
718 *
719 * All functions bound via
720 * `{@link xdc.runtime.System#atexit System_atexit}` or the ANSI C
721 * Standard Library `atexit` function are then executed.
722 *
723 * @param(stat) exit status to return to calling environment.
724 */
725 Void exit(Int stat);
726
727 /*!
728 * ======== getThreadType ========
729 * Get the current thread type
730 *
731 * @b(returns) Current thread type
732 */
733 ThreadType getThreadType();
734
735 /*!
736 * @_nodoc
737 * ======== setThreadType ========
738 * Set the current thread type
739 *
740 * Called by the various threadType owners.
741 *
742 * @param(ttype) New thread type value
743 * @b(returns) Previous thread type
744 */
745 ThreadType setThreadType(ThreadType ttype);
746
747 /*!
748 * ======== setCpuFreq ========
749 * Set CPU Frequency in Hz
750 *
751 * This API is not thread safe. Please use appropriate locks.
752 */
753 Void setCpuFreq(Types.FreqHz *freq);
754
755 /*!
756 * ======== getCpuFreq ========
757 * Get CPU frequency in Hz
758 *
759 * This API is not thread safe. Please use appropriate locks.
760 */
761 Void getCpuFreq(Types.FreqHz *freq);
762
763 /*!
764 * @_nodoc
765 * ======== getCpuFrequency ========
766 * Get CPU frequency in Hz.
767 *
768 * This function is currently used by UIA and is called in the
769 * UIAMetaData validate() function.
770 * NOTE: Javascript does not support UInt64, so this only works
771 * if the frequency is less than 4GHz. Keep this function for
772 * backwards compatability (for awhile).
773 */
774 metaonly UInt64 getCpuFrequency();
775
776 /*!
777 * @_nodoc
778 * ======== getCpuFreqMeta ========
779 * Get CPU frequency in Hz.
780 *
781 * This function is currently used by UIA and is called in the
782 * UIAMetaData validate() function.
783 */
784 metaonly Types.FreqHz getCpuFreqMeta();
785
786 /*!
787 * @_nodoc
788 * ======== getTimestampFrequency ========
789 * Get timestamp frequency in Hz. If we don't know the timestamp
790 * frequency of the device, return 0.
791 *
792 * This function is currently used by UIA and is called in the
793 * UIAMetaData validate() function.
794 * NOTE: Javascript does not support UInt64, so this only works
795 * if the frequency is less than 4GHz. Keep this function for
796 * backwards compatability (for awhile).
797 */
798 metaonly UInt64 getTimestampFrequency();
799
800 /*!
801 * @_nodoc
802 * ======== getTimestampFreqMeta ========
803 * Get timestamp frequency in Hz. If we don't know the timestamp
804 * frequency of the device, return 0.
805 *
806 * This function is currently used by UIA and is called in the
807 * UIAMetaData validate() function.
808 */
809 metaonly Types.FreqHz getTimestampFreqMeta();
810
811 /*!
812 * @_nodoc
813 * ======== getDefaultTimestampProvider ========
814 * Returns the name of the TimestampProvider module BIOS will set
815 * xdc.runtime.Timestamp.SupportProxy to if it hasn't been configured
816 * in the user's config script.
817 *
818 * This function is meant to be used by modules that have their own
819 * TimestampProvider proxies if they want to initialize them to the
820 * default xdc.runtime.Timestamp.SupportProxy binding selected by BIOS:
821 *
822 * if (!this.$written("TimestampProxy")) {
823 * if (xdc.runtime.$written("Timestamp.SupportProxy") {
824 * this.TimestampProxy = xdc.runtime.Timestamp.SupportProxy;
825 * }
826 * else {
827 * this.TimestampProxy = xdc.module(BIOS.getDefaultTimestampProvider());
828 * }
829 * }
830 */
831 metaonly String getDefaultTimestampProvider();
832
833 internal:
834
835 836 837 838 839 840 841
842 metaonly config Bool buildingAppLib = true;
843
844 845 846 847
848 metaonly config Bool includeXdcRuntime = false;
849
850 851 852 853
854 metaonly config String libDir = null;
855
856 857 858 859
860 metaonly String getCCOpts(String target);
861
862 863 864 865
866 struct intSize {
867 Int intSize;
868 }
869
870 871 872 873 874 875
876 metaonly config Char bitsPerInt;
877
878 879 880 881 882 883
884 config Void (*installedErrorHook)(Error.Block *);
885
886 887 888 889 890
891 Void errorRaiseHook(Error.Block *eb);
892
893 894 895 896
897 Void startFunc();
898
899 900 901 902
903 Void atExitFunc(Int stat);
904
905 906 907 908
909 Void exitFunc(Int stat);
910
911 912 913 914 915 916
917 Void registerRTSLock();
918
919 920 921 922 923 924
925 Void removeRTSLock();
926
927 928 929 930
931 Void rtsLock();
932
933 934 935 936
937 Void rtsUnlock();
938
939 940 941
942 Void nullFunc();
943
944 945 946
947 function fireFrequencyUpdate(newFreq);
948
949 950 951 952
953 proxy RtsGateProxy inherits xdc.runtime.IGateProvider;
954
955 956 957 958
959 typedef Void (*StartFuncPtr)(void);
960
961 962 963 964
965 typedef Void (*ExitFuncPtr)(Int);
966
967 968 969
970 struct Module_State {
971 Types.FreqHz cpuFreq;
972 UInt rtsGateCount;
973 IArg rtsGateKey;
974 RtsGateProxy.Handle rtsGate;
975 ThreadType threadType;
976
977 ThreadType smpThreadType[];
978
979 volatile StartFuncPtr startFunc;
980 volatile ExitFuncPtr exitFunc;
981 };
982 }