1    /*
     2     * Copyright (c) 2015-2019, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     */
    32    /*
    33     *  ======== BIOS.xdc ========
    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   /* to check for codegen compatibility */
   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        /* REQ_TAG(SYSBIOS-636) */
   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         *  ======== buildingAppLib ========
   971         *  Enable custom build of SYS/BIOS from source
   972         *
   973         *  true = building application-specific custom lib
   974         *  false = building internal instrumented/nonInstrumented lib
   975         */
   976        metaonly config Bool buildingAppLib = true;
   977    
   978        /*
   979         *  ======== libDir ========
   980         *  Specify output library directory
   981         */
   982        metaonly config String libDir = null;
   983    
   984        /*
   985         *  @_nodoc
   986         *  ======== codeCoverageEnabled ========
   987         *  Setting this to 'true' will tweak other settings for
   988         *  code coverage.
   989         *
   990         *  For example, by setting this to true, the code that melts
   991         *  away when hook.length is 0 does not melt away.
   992         */
   993        metaonly config Bool codeCoverageEnabled = false;
   994    
   995        /*
   996         *  ======== getCCOpts ========
   997         *  Get the compiler options necessary to build
   998         */
   999        metaonly String getCCOpts(String target);
  1000    
  1001        /*
  1002         *  ======== intSize ========
  1003         *  Used to determine number of bits in an Int
  1004         */
  1005        struct intSize {
  1006            Int intSize;
  1007        }
  1008    
  1009        /*
  1010         *  ======== bitsPerInt ========
  1011         *  Number of bits in an integer
  1012         *
  1013         *  Used for error checking
  1014         */
  1015        metaonly config Char bitsPerInt;
  1016    
  1017        /*
  1018         *  ======== installedErrorHook ========
  1019         *  User/default Error.raiseHook
  1020         *
  1021         *  BIOS_errorRaiseHook() calls this after setting threadType
  1022         *  to Main so that GateMutex's threadType check will
  1023         *  pass.
  1024         */
  1025        config Void (*installedErrorHook)(Error.Block *);
  1026    
  1027        /*
  1028         *  ======== errorRaiseHook ========
  1029         *  Error.raiseHook that sets threadType to Main so
  1030         *  threadType checking Asserts will pass.
  1031         */
  1032        Void errorRaiseHook(Error.Block *eb);
  1033    
  1034        /*
  1035         *  ======== startFunc ========
  1036         *  Generated BIOS_start function
  1037         */
  1038        Void startFunc();
  1039    
  1040        /*
  1041         *  ======== atExitFunc ========
  1042         *  Generated BIOS_atExitFunc function
  1043         */
  1044        Void atExitFunc(Int stat);
  1045    
  1046        /*
  1047         *  ======== exitFunc ========
  1048         *  Generated BIOS_exitFunc function
  1049         */
  1050        Void exitFunc(Int stat);
  1051    
  1052        /*
  1053         *  ======== registerRTSLock ========
  1054         *  Register the RTS lock
  1055         *
  1056         *  Added as a startup function in BIOS.xs.
  1057         */
  1058        Void registerRTSLock();
  1059    
  1060        /*
  1061         *  ======== removeRTSLock ========
  1062         *  Remove the RTS locks
  1063         *
  1064         *  This function is called by BIOS_exit().
  1065         */
  1066        Void removeRTSLock();
  1067    
  1068        /*
  1069         *  ======== rtsLock ========
  1070         *  Called by rts _lock() function
  1071         */
  1072        Void rtsLock();
  1073    
  1074        /*
  1075         *  ======== rtsUnLock ========
  1076         *  Called by rts _unlock() function
  1077         */
  1078        Void rtsUnlock();
  1079    
  1080        /*
  1081         *  ======== nullFunc ========
  1082         */
  1083        Void nullFunc();
  1084    
  1085        /*
  1086         *  ======== fireFrequencyUpdate ========
  1087         */
  1088        function fireFrequencyUpdate(newFreq);
  1089    
  1090        /*
  1091         *  ======== RtsGateProxy ========
  1092         *  Gate proxy to be used for the rts gate
  1093         */
  1094        proxy RtsGateProxy inherits xdc.runtime.IGateProvider;
  1095    
  1096        /*
  1097         *  ======== StartFuncPtr ========
  1098         *  Function prototype for the generated BIOS_start
  1099         */
  1100        typedef Void (*StartFuncPtr)(void);
  1101    
  1102        /*
  1103         *  ======== ExitFuncPtr ========
  1104         *  Function prototype for the generated BIOS_exit
  1105         */
  1106        typedef Void (*ExitFuncPtr)(Int);
  1107    
  1108        /*
  1109         *  ======== Module_State ========
  1110         */
  1111        struct Module_State {
  1112            Types.FreqHz        cpuFreq;            /* in KHz */
  1113            UInt                rtsGateCount;       /* count for nesting */
  1114            IArg                rtsGateKey;         /* key for unlocking */
  1115            RtsGateProxy.Handle rtsGate;            /* gate for RTS calls */
  1116            ThreadType          threadType;         /* Curr Thread Type */
  1117                                                    /* (Hwi, Swi, Task) */
  1118            ThreadType          smpThreadType[];    /* SMP Core specific */
  1119                                                    /* Thread Type */
  1120            volatile StartFuncPtr startFunc;
  1121            volatile ExitFuncPtr  exitFunc;
  1122        };
  1123    }