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