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.IHeap;
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 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 * supported 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 is built with logging and
247 * assertions enabled.
248 *
249 * @field(LibType_NonInstrumented) The library is built with logging and
250 * assertions disabled.
251 *
252 * @field(LibType_Custom) The library is built using the options
253 * specified by {@link #customCCOpts}. Program optimization is performed
254 * to reduce the size of the executable and improve its performance.
255 * Enough debug information is retained to allow you to step through the
256 * application code in CCS and locate global variables.
257 *
258 * @field(LibType_Debug) This setting is similar to the LibType_Custom
259 * setting, however, no program optimization is performed. The resulting
260 * executable is fully debuggable, and you can step into SYS/BIOS code.
261 * The tradeoff is that the executable is larger and runs slower than
262 * builds that use the LibType_Custom option.
263 *
264 * @see #libType
265 */
266 enum LibType {
267 LibType_Instrumented, /*! Instrumented (Asserts and Logs enabled) */
268 LibType_NonInstrumented, /*! Non-instrumented (Asserts and Logs disabled) */
269 LibType_Custom, /*! Custom (Fully configurable) */
270 LibType_Debug /*! Debug (Fully configurable) */
271 };
272
273 /*! Used in APIs that take a timeout to specify wait forever */
274 const UInt WAIT_FOREVER = ~(0U);
275
276 /*! Used in APIs that take a timeout to specify no waiting */
277 const UInt NO_WAIT = 0U;
278
279 /*! User startup function type definition. */
280 typedef Void (*StartupFuncPtr)(Void);
281
282 /*!
283 * ======== ModuleView ========
284 * @_nodoc
285 */
286 metaonly struct ModuleView {
287 String currentThreadType[];
288 String rtsGateType;
289 Int cpuFreqLow;
290 Int cpuFreqHigh;
291 Bool clockEnabled;
292 Bool swiEnabled;
293 Bool taskEnabled;
294 String startFunc;
295 }
296
297 /*!
298 * ======== ErrorView ========
299 * @_nodoc
300 */
301 metaonly struct ErrorView {
302 String mod;
303 String tab;
304 String inst;
305 String field;
306 String message;
307 }
308
309 /*!
310 * ======== rovViewInfo ========
311 * @_nodoc
312 */
313 @Facet
314 metaonly config ViewInfo.Instance rovViewInfo =
315 ViewInfo.create({
316 viewMap: [
317 [
318 'Module',
319 {
320 type: ViewInfo.MODULE,
321 viewInitFxn: 'viewInitModule',
322 structName: 'ModuleView'
323 }
324 ],
325 [
326 'Scan for errors...',
327 {
328 type: ViewInfo.MODULE_DATA,
329 viewInitFxn: 'viewInitErrorScan',
330 structName: 'ErrorView'
331 }
332 ],
333 ]
334 });
335
336 /*!
337 * ======== libType ========
338 * SYS/BIOS Library type
339 *
340 * The SYS/BIOS runtime is built in the form of a library that is
341 * linked with your application. Several forms of this library are
342 * supported by the SYS/BIOS product. This configuration parameter
343 * allows you to select the form of the SYS/BIOS library to use.
344 *
345 * The default value of libType is
346 * {@link #LibType_Instrumented BIOS_LibType_Instrumented}. For a
347 * complete list of options and what they offer see {@link #LibType}.
348 */
349 metaonly config LibType libType = LibType_Instrumented;
350
351 /*!
352 * ======== customCCOpts ========
353 * Compiler options used when building a custom SYS/BIOS library
354 *
355 * When {@link #libType BIOS.libType} is set to
356 * {@link #LibType_Custom BIOS_LibType_Custom} or
357 * {@link #LibType_Debug BIOS_LibType_Debug},
358 * this string contains the options passed to the compiler during any
359 * build of the SYS/BIOS sources.
360 *
361 * In addition to the options specified by `BIOS.customCCOpts`, several
362 * `-D` and `-I` options are also passed to the compiler. The options
363 * specified by `BIOS.customCCOpts` are, however, the first options passed
364 * to the compiler on the command line.
365 *
366 * To view the custom compiler options, add the following line to your
367 * config script:
368 *
369 * @p(code)
370 * print(BIOS.customCCOpts);
371 * @p
372 *
373 * When {@link #libType BIOS.libType} is set to
374 * {@link #LibType_Custom BIOS_LibType_Custom},
375 * `BIOS.customCCOpts` is initialized to settings that create a highly
376 * optimized SYS/BIOS library.
377 *
378 * When {@link #libType BIOS.libType} is set to
379 * {@link #LibType_Debug BIOS_LibType_Debug},
380 * `BIOS.customCCOpts` is initialized to settings that create a
381 * non-optimized SYS/BIOS library that can be used to single-step through
382 * the APIs with the CCS debugger.
383 *
384 * More information about using `BIOS.customCCOpts` is provided in the
385 * {@link http://processors.wiki.ti.com/index.php/SYS/BIOS_FAQs SYS/BIOS FAQs}.
386 *
387 * @a(Warning)
388 * The default value of `BIOS.customCCOpts`, which is derived from the
389 * target specified by your configuration, includes runtime model options
390 * (such as endianess) that must be the same for all sources built and
391 * linked into your application. You must not change or add any options
392 * that can alter the runtime model specified by the default value of
393 * `BIOS.customCCOpts`.
394 *
395 * @a(Warning)
396 * Setting `BIOS.libType` overwrites `BIOS.customCCOpts`. Therefore, if an
397 * application's *.cfg file sets both these config params, the libType must
398 * be set before customCCOpts so the changes to customCCOpts persist.
399 */
400 metaonly config String customCCOpts;
401
402 /*!
403 * ======== includeXdcRuntime ========
404 * Include xdc.runtime sources in custom built library
405 *
406 * By default, the xdc.runtime library sources are not included in the
407 * custom SYS/BIOS library created for the application. Instead,
408 * the pre-built xdc.runtime library is provided by the respective target
409 * used to build the application.
410 *
411 * Setting this parameter to true will cause the xdc.runtime library
412 * sources to be included in the custom SYS/BIOS library. This setting
413 * yields the most efficient library in both code size and runtime
414 * performance.
415 */
416 metaonly config Bool includeXdcRuntime = false;
417
418 /*!
419 * ======== smpEnabled ========
420 * Enables multi core SMP task scheduling
421 *
422 * This functionality is available on only select multi-core devices.
423 *
424 * More information about SMP/BIOS is provided here:
425 * {@link http://processors.wiki.ti.com/index.php/SMP/BIOS SMP/BIOS}.
426 */
427 config Bool smpEnabled = false;
428
429 /*!
430 * ======== mpeEnabled ========
431 * Enables Memory Protection Extensions (MPE)
432 *
433 * SYS/BIOS memory protection extensions add the capability to
434 * create privileged and unprivileged tasks as well as define
435 * access privileges for the unprivileged tasks.
436 *
437 * This functionality is available on only select devices.
438 */
439 config Bool mpeEnabled = false;
440
441 /*!
442 * ======== psaEnabled ========
443 * Enables ARM's Platform Security Architecture (PSA) extensions
444 *
445 * This functionality is available on only select devices.
446 */
447 metaonly config Bool psaEnabled = false;
448
449 /*!
450 * ======== cpuFreq ========
451 * CPU frequency in Hz
452 *
453 * This configuration parameter allow SYS/BIOS to convert various
454 * periods between timer ticks (or instruction cycles) and real-time
455 * units. For example, timer periods expressed in micro-seconds need
456 * to be converted into timer ticks in order to properly program the
457 * timers.
458 *
459 * The default value of this parameter is obtained from the platform
460 * (the clockRate property of {@link xdc.cfg.Program#cpu Program.cpu})
461 * which is the CPU clock rate when the processor is reset.
462 *
463 * @a(Example)
464 * If CPU frequency is 720MHz, the following configuration script
465 * configures SYS/BIOS with the proper clock frequency:
466 * @p(code)
467 * var BIOS = xdc.useModule('ti.sysbios.BIOS');
468 * BIOS.cpuFreq.hi = 0;
469 * BIOS.cpuFreq.lo = 720000000;
470 * @p
471 */
472 config Types.FreqHz cpuFreq;
473
474 /*!
475 * ======== runtimeCreatesEnabled ========
476 * Runtime instance creation enable flag.
477 *
478 * true = Mod_create() & Mod_delete() callable at runtime
479 * false = Mod_create() & Mod_delete() not callable at runtime
480 */
481
482 config Bool runtimeCreatesEnabled = true;
483
484 /*!
485 * ======== taskEnabled ========
486 * SYS/BIOS Task services enable flag
487 *
488 * The following behaviors occur when {@link #taskEnabled} is
489 * set to false:
490 *
491 * @p(blist)
492 * - Static {@link ti.sysbios.knl.Task Task} creation will
493 * result in a fatal build error.
494 * - The Idle task object is not created.
495 * (The Idle functions are invoked within the {@link #start()}
496 * thread.)
497 * - Runtime calls to Task_create will trigger an assertion violation
498 * via {@link xdc.runtime.Assert#isTrue}.
499 * @p
500 *
501 * @a(note)
502 * {@link #taskEnabled BIOS.taskEnabled} must be true when in SMP mode.
503 * See {@link #smpEnabled BIOS.smpEnabled}.
504 */
505 config Bool taskEnabled = true;
506
507 /*!
508 * ======== swiEnabled ========
509 * SYS/BIOS Swi services enable flag
510 *
511 * The following behaviors occur when {@link #swiEnabled} is
512 * set to false:
513 *
514 * @p(blist)
515 * - Static {@link ti.sysbios.knl.Swi Swi} creation will
516 * result in a fatal build error.
517 * - See other effects as noted for {@link #clockEnabled} = false;
518 * - Runtime calls to Swi_create will trigger an assertion violation
519 * via {@link xdc.runtime.Assert#isTrue}.
520 * @p
521 *
522 * @a(note)
523 * {@link #swiEnabled BIOS.swiEnabled} must be true when in SMP mode.
524 * See {@link #smpEnabled BIOS.smpEnabled}.
525 */
526 config Bool swiEnabled = true;
527
528 /*!
529 * ======== clockEnabled ========
530 * SYS/BIOS Clock services enable flag
531 *
532 * The following behaviors occur when {@link #clockEnabled} is
533 * set to false:
534 *
535 * @p(blist)
536 * - Static Clock creation will result in a fatal build error.
537 * - No Clock Swi is created.
538 * - The {@link ti.sysbios.knl.Clock#tickSource Clock_tickSource}
539 * is set to
540 * {@link ti.sysbios.knl.Clock#TickSource_NULL Clock_TickSource_NULL}
541 * to prevent a Timer object from being created.
542 * - For APIs that take a timeout, values other than {@link #NO_WAIT}
543 * will be equivalent to {@link #WAIT_FOREVER}.
544 * @p
545 */
546 config Bool clockEnabled = true;
547
548 /*!
549 * ======== assertsEnabled ========
550 * SYS/BIOS Assert checking in Custom SYS/BIOS library enable flag
551 *
552 * When set to true, Assert checking code is compiled into
553 * the custom library created when {@link #libType BIOS.libType}
554 * is set to {@link #LibType_Custom BIOS_LibType_Custom} or
555 * {@link #LibType_Debug BIOS_LibType_Debug}.
556 *
557 * When set to false, Assert checking code is removed from the custom
558 * library created when BIOS.libType is set to BIOS.LibType_Custom
559 * or BIOS.LibType_Debug.
560 * This option can considerably improve runtime performance as well
561 * significantly reduce the application's code size.
562 *
563 * see {@link #libType BIOS.libType}.
564 */
565 metaonly config Bool assertsEnabled = true;
566
567 /*!
568 * ======== logsEnabled ========
569 * SYS/BIOS Log support in Custom SYS/BIOS library enable flag
570 *
571 * When set to true, SYS/BIOS execution Log code is compiled into
572 * the custom library created when {@link #libType BIOS.libType}
573 * is set to {@link #LibType_Custom BIOS_LibType_Custom} or
574 * {@link #LibType_Debug BIOS_LibType_Debug}.
575 *
576 * When set to false, all Log code is removed from
577 * the custom library created when BIOS.libType = BIOS.LibType_Custom
578 * or BIOS.LibType_Debug.
579 * This option can considerably improve runtime performance as well
580 * significantly reduce the application's code size.
581 *
582 * see {@link #libType BIOS.libType}.
583 *
584 * @a(Warning) Since interrupts
585 * are enabled when logs are generated, this setting will have the
586 * side effect of requiring task stacks to be sized large enough
587 * to absorb two interrupt contexts rather than one.
588 * See the discussion on task stacks in {@link ti.sysbios.knl.Task
589 * Task} for more information.
590 */
591 metaonly config Bool logsEnabled = true;
592
593 /*!
594 * ======== defaultKernelHeapInstance ========
595 * Default Kernel heap instance
596 *
597 * If SYS/BIOS Memory Protection Extensions
598 * {@link #mpeEnabled BIOS.mpeEnabled} are enabled, a dedicated kernel
599 * heap is created. This heap is used for allocating kernel objects
600 * when create() calls are made. The kernel heap resides in privileged
601 * memory and is protected against unauthorized access from User Tasks.
602 */
603 config IHeap.Handle defaultKernelHeapInstance = null;
604
605 /*!
606 * ======== kernelHeapSize ========
607 * Kernel heap size, units are in MAUs
608 *
609 * If SYS/BIOS Memory Protection Extensions
610 * {@link #mpeEnabled BIOS.mpeEnabled} are enabled, a dedicated kernel
611 * heap is created. This heap is used for allocating kernel objects
612 * when create() calls are made. The kernel heap resides in privileged
613 * memory and is protected against unauthorized access from User Tasks.
614 */
615 config SizeT kernelHeapSize = 0x1000;
616
617 /*!
618 * ======== kernelHeapSection ========
619 * Kernel heap section name
620 */
621 config CString kernelHeapSection = ".kernel_heap";
622
623 /*!
624 * ======== heapSize ========
625 * Size of system heap, units are in MAUs
626 *
627 * The system heap is, by default, used to allocate instance object
628 * state structures, such as {@link ti.sysbios.knl.Task Task} objects
629 * and their stacks, {@link ti.sysbios.knl.Semaphore Semaphore} objects,
630 * etc.
631 *
632 * If the application configuration does not set
633 * Memory.defaultHeapInstance, then SYS/BIOS will create a
634 * {@link ti.sysbios.heaps.HeapMem HeapMem} heap of this size. This
635 * heap will be assigned to
636 * {@link xdc.runtime.Memory#defaultHeapInstance Memory.defaultHeapInstance}
637 * and will therefore be used as the default system heap. This heap
638 * will also be used by the SYS/BIOS version of the standard C library
639 * functions malloc(), calloc() and free().
640 *
641 * @a(Note)
642 * If SYS/BIOS Memory Protection Extensions
643 * {@link #mpeEnabled BIOS.mpeEnabled} are enabled, a dedicated kernel heap
644 * is allocated (see
645 * {@link #defaultKernelHeapInstance BIOS.defaultKernelHeapInstance}). The
646 * System heap is placed in a public section (accessible from
647 * privileged and user Tasks) called ".public_heap" by default.
648 */
649 config SizeT heapSize = 0x1000;
650
651 /*!
652 * ======== heapSection ========
653 * Section to place the system heap
654 *
655 * This configuration parameter allows you to specify a named output
656 * section that will contain the SYS/BIOS system heap. The system heap
657 * is, by default, used to allocate {@link ti.sysbios.knl.Task Task}
658 * stacks and instance object state structures. So, giving this section
659 * a name and explicitly placing it via a linker command file can
660 * significantly improve system performance.
661 *
662 * If heapSection is `null` (or `undefined`) the system heap is placed
663 * in the target's default data section.
664 *
665 * @a(Note)
666 * If SYS/BIOS Memory Protection Extensions
667 * {@link #mpeEnabled BIOS.mpeEnabled} are enabled, a dedicated kernel heap
668 * is allocated (see
669 * {@link #defaultKernelHeapInstance BIOS.defaultKernelHeapInstance}). The
670 * System heap is placed in a public section (accessible from
671 * privileged and user Tasks) called ".public_heap" by default.
672 */
673 config String heapSection = null;
674
675 /*!
676 * ======== heapTrackEnabled ========
677 * Use HeapTrack with system default heap
678 *
679 * This configuration parameter will add a HeapTrack instance on top of
680 * the system heap. HeapTrack adds a tracker packet to every allocated
681 * buffer and displays the information in RTOS Object Viewer (ROV).
682 * An assert will be raised on a free if there was a buffer overflow.
683 */
684 config Bool heapTrackEnabled = false;
685
686 /*!
687 * ======== setupSecureContext ========
688 * @_nodoc
689 * Sets up a secure context when using secure version of BIOS
690 *
691 * This is available for some C66 secure devices only.
692 * This parameter take effect only when 'useSK' is set to true.
693 * If set to true, a call to Hwi_setupSC() is done in a last function.
694 */
695 config Bool setupSecureContext = false;
696
697 /*!
698 * ======== useSK ========
699 * @_nodoc
700 * use the secure version of BIOS
701 *
702 * This is available for some C66 secure devices only.
703 * This parameter can only be used with the custom build.
704 */
705 config Bool useSK = false;
706
707 /*!
708 * ======== rtsGateType ========
709 * Gate to make sure TI RTS library APIs are re-entrant
710 *
711 * The application gets to determine the type of gate (lock) that is used
712 * in the TI RTS library. The gate will be used to guarantee re-entrancy
713 * of the RTS APIs.
714 *
715 * The type of gate depends on the type of threads that are going to
716 * be calling into the RTS library. For example, if both Swi and Task
717 * threads are going to be calling the RTS library's printf, GateSwi
718 * should be used. In this case, Hwi threads are not impacted (i.e.
719 * disabled) during the printf calls from the Swi or Task threads.
720 *
721 * If NoLocking is used, the RTS lock is not plugged and re-entrancy for
722 * the TI RTS library calls are not guaranteed. The application can plug
723 * the RTS locks directly if it wants.
724 *
725 * Numerous gate types are provided by SYS/BIOS. Each has its advantages
726 * and disadvantages. The following list summarizes when each type is
727 * appropriate for protecting an underlying non-reentrant RTS library.
728 * @p(dlist)
729 * - {@link #GateHwi}:
730 * Interrupts are disabled and restored to maintain re-entrancy.
731 * Use if only making RTS calls from a Hwi, Swi and/or Task.
732 *
733 * - {@link #GateSwi}:
734 * Swis are disabled and restored to maintain re-entrancy. Use if
735 * only making RTS calls from a Swi and/or Task.
736 *
737 * - {@link #GateMutex}:
738 * A single mutex is used to maintain re-entrancy. Use if only
739 * making RTS calls from a Task. Blocks only Tasks that are
740 * also trying to execute critical regions of RTS library.
741 *
742 * - {@link #GateMutexPri}:
743 * A priority inheriting mutex is used to maintain re-entrancy.
744 * Blocks only Tasks that are also trying to execute critical
745 * regions of RTS library. Raises the priority of the Task that
746 * is executing the critical region in the RTS library to the
747 * level of the highest priority Task that is block by the mutex.
748 * @p
749 *
750 * The default value of rtsGateType depends on the type of threading
751 * model enabled by other configuration parameters.
752 * If {@link #taskEnabled} is true, {@link #GateMutex} is used.
753 * If {@link #swiEnabled} is true and {@link #taskEnabled} is false:
754 * {@link #GateSwi} is used.
755 * If both {@link #swiEnabled} and {@link #taskEnabled} are false:
756 * {@link xdc.runtime#GateNull} is used.
757 *
758 * If {@link #taskEnabled} is false, the user should not select
759 * {@link #GateMutex} (or other Task level gates). Similarly, if
760 * {@link #taskEnabled} and {@link #swiEnabled}are false, the user
761 * should not select {@link #GateSwi} or the Task level gates.
762 */
763 metaonly config RtsLockType rtsGateType;
764
765 /*!
766 * ======== startupFxns ========
767 * Functions to be executed at the beginning of BIOS_start()
768 *
769 * These user (or middleware) functions are executed before Hwis,
770 * Swis, and Tasks are started.
771 */
772 metaonly config StartupFuncPtr startupFxns[] = [];
773
774 /*!
775 * ======== version ========
776 * SYS/BIOS version number macro
777 *
778 * This macro has a hex value that represents the SYS/BIOS version
779 * number. The hex value has the version format 0xMmmpp, where
780 * M is a single digit Major number, mm is a 2 digit minor number
781 * and pp is a 2 digit patch number.
782 *
783 * Example: A macro hex value of 0x64501 implies that the SYS/BIOS
784 * product version number is 6.45.01
785 */
786 const UInt32 version = 0x68302;
787
788 /*!
789 * ======== addUserStartupFunction ========
790 * @_nodoc
791 * Statically add a function to the startupFxns table.
792 */
793 metaonly Void addUserStartupFunction(StartupFuncPtr func);
794
795 /*!
796 * ======== linkedWithIncorrectBootLibrary ========
797 * Application was linked with incorrect Boot library
798 *
799 * This function has a loop that spins forever. If execution
800 * reaches this function, it indicates that the application
801 * was linked with an incorrect boot library and the XDC
802 * runtime startup functions did not get run. This can happen
803 * if the code gen tool's RTS library was before SYS/BIOS's
804 * generated linker cmd file on the link line.
805 */
806 Void linkedWithIncorrectBootLibrary();
807
808 /*!
809 * ======== start ========
810 * Start SYS/BIOS
811 *
812 * The user's main() function is required to call this function
813 * after all other user initializations have been performed.
814 *
815 * This function does not return.
816 *
817 * This function performs any remaining SYS/BIOS initializations
818 * and then transfers control to the highest priority ready
819 * task if {@link #taskEnabled} is true. If {@link #taskEnabled}
820 * is false, control is transferred directly to the Idle Loop.
821 *
822 * The SYS/BIOS start sequence is as follows:
823 * @p(blist)
824 * - Invoke all the functions in the {@link #startupFxns} array.
825 * - call {@link ti.sysbios.hal.Hwi#enable Hwi_startup()}
826 * to enable interrupts.
827 * - if {@link #swiEnabled} is true, call
828 * {@link ti.sysbios.knl.Swi#enable Swi_startup()} to enable
829 * the Swi scheduler.
830 * - Start any statically created or constructed Timers
831 * in the {@link ti.sysbios.hal.Timer#StartMode Timer_StartMode_AUTO}
832 * mode.
833 * - if {@link #taskEnabled} is true, enable the Task scheduler
834 * and transfer the execution thread to the highest priority
835 * task in the {@link ti.sysbios.knl.Task#Mode Task_Mode_READY}
836 * mode.
837 * - Otherwise, fall directly into the Idle Loop.
838 * @p
839 *
840 */
841 Void start();
842
843 /*!
844 * ======== exit ========
845 * Exit currently running SYS/BIOS executable
846 *
847 * This function is called when a SYS/BIOS executable needs to terminate
848 * normally. This function sets the internal SYS/BIOS threadType to
849 * {@link #ThreadType_Main} and then calls
850 * {@link xdc.runtime.System#exit System_exit}(stat), passing along
851 * the 'stat' argument.
852 *
853 * All functions bound via
854 * `{@link xdc.runtime.System#atexit System_atexit}` or the ANSI C
855 * Standard Library `atexit` function are then executed.
856 *
857 * @param(stat) exit status to return to calling environment.
858 */
859 Void exit(Int stat);
860
861 /*!
862 * ======== getThreadType ========
863 * Get the current thread type
864 *
865 * @b(returns) Current thread type
866 */
867 ThreadType getThreadType();
868
869 /*!
870 * @_nodoc
871 * ======== setThreadType ========
872 * Set the current thread type
873 *
874 * Called by the various threadType owners.
875 *
876 * @param(ttype) New thread type value
877 * @b(returns) Previous thread type
878 */
879 ThreadType setThreadType(ThreadType ttype);
880
881 /*!
882 * ======== setCpuFreq ========
883 * Set CPU Frequency in Hz
884 *
885 * This API is not thread safe. Please use appropriate locks.
886 */
887 Void setCpuFreq(Types.FreqHz *freq);
888
889 /*!
890 * ======== getCpuFreq ========
891 * Get CPU frequency in Hz
892 *
893 * This API is not thread safe. Please use appropriate locks.
894 */
895 Void getCpuFreq(Types.FreqHz *freq);
896
897 /*!
898 * @_nodoc
899 * ======== getCpuFrequency ========
900 * Get CPU frequency in Hz.
901 *
902 * This function is currently used by UIA and is called in the
903 * UIAMetaData validate() function.
904 * NOTE: Javascript does not support UInt64, so this only works
905 * if the frequency is less than 4GHz. Keep this function for
906 * backwards compatibility (for awhile).
907 */
908 metaonly UInt64 getCpuFrequency();
909
910 /*!
911 * @_nodoc
912 * ======== getCpuFreqMeta ========
913 * Get CPU frequency in Hz.
914 *
915 * This function is currently used by UIA and is called in the
916 * UIAMetaData validate() function.
917 */
918 metaonly Types.FreqHz getCpuFreqMeta();
919
920 /*!
921 * @_nodoc
922 * ======== getTimestampFrequency ========
923 * Get timestamp frequency in Hz. If we don't know the timestamp
924 * frequency of the device, return 0.
925 *
926 * This function is currently used by UIA and is called in the
927 * UIAMetaData validate() function.
928 * NOTE: Javascript does not support UInt64, so this only works
929 * if the frequency is less than 4GHz. Keep this function for
930 * backwards compatability (for awhile).
931 */
932 metaonly UInt64 getTimestampFrequency();
933
934 /*!
935 * @_nodoc
936 * ======== getTimestampFreqMeta ========
937 * Get timestamp frequency in Hz. If we don't know the timestamp
938 * frequency of the device, return 0.
939 *
940 * This function is currently used by UIA and is called in the
941 * UIAMetaData validate() function.
942 */
943 metaonly Types.FreqHz getTimestampFreqMeta();
944
945 /*!
946 * @_nodoc
947 * ======== getDefaultTimestampProvider ========
948 * Returns the name of the TimestampProvider module BIOS will set
949 * xdc.runtime.Timestamp.SupportProxy to if it hasn't been configured
950 * in the user's config script.
951 *
952 * This function is meant to be used by modules that have their own
953 * TimestampProvider proxies if they want to initialize them to the
954 * default xdc.runtime.Timestamp.SupportProxy binding selected by BIOS:
955 *
956 * if (!this.$written("TimestampProxy")) {
957 * if (xdc.runtime.$written("Timestamp.SupportProxy") {
958 * this.TimestampProxy = xdc.runtime.Timestamp.SupportProxy;
959 * }
960 * else {
961 * this.TimestampProxy = xdc.module(BIOS.getDefaultTimestampProvider());
962 * }
963 * }
964 */
965 metaonly String getDefaultTimestampProvider();
966
967 internal:
968
969 970 971 972 973 974 975
976 metaonly config Bool buildingAppLib = true;
977
978 979 980 981
982 metaonly config String libDir = null;
983
984 985 986 987 988 989 990 991 992
993 metaonly config Bool codeCoverageEnabled = false;
994
995 996 997 998
999 metaonly String getCCOpts(String target);
1000
1001 1002 1003 1004
1005 struct intSize {
1006 Int intSize;
1007 }
1008
1009 1010 1011 1012 1013 1014
1015 metaonly config Char bitsPerInt;
1016
1017 1018 1019 1020 1021 1022 1023 1024
1025 config Void (*installedErrorHook)(Error.Block *);
1026
1027 1028 1029 1030 1031
1032 Void errorRaiseHook(Error.Block *eb);
1033
1034 1035 1036 1037
1038 Void startFunc();
1039
1040 1041 1042 1043
1044 Void atExitFunc(Int stat);
1045
1046 1047 1048 1049
1050 Void exitFunc(Int stat);
1051
1052 1053 1054 1055 1056 1057
1058 Void registerRTSLock();
1059
1060 1061 1062 1063 1064 1065
1066 Void removeRTSLock();
1067
1068 1069 1070 1071
1072 Void rtsLock();
1073
1074 1075 1076 1077
1078 Void rtsUnlock();
1079
1080 1081 1082
1083 Void nullFunc();
1084
1085 1086 1087
1088 function fireFrequencyUpdate(newFreq);
1089
1090 1091 1092 1093
1094 proxy RtsGateProxy inherits xdc.runtime.IGateProvider;
1095
1096 1097 1098 1099
1100 typedef Void (*StartFuncPtr)(void);
1101
1102 1103 1104 1105
1106 typedef Void (*ExitFuncPtr)(Int);
1107
1108 1109 1110
1111 struct Module_State {
1112 Types.FreqHz cpuFreq;
1113 UInt rtsGateCount;
1114 IArg rtsGateKey;
1115 RtsGateProxy.Handle rtsGate;
1116 ThreadType threadType;
1117
1118 ThreadType smpThreadType[];
1119
1120 volatile StartFuncPtr startFunc;
1121 volatile ExitFuncPtr exitFunc;
1122 };
1123 }