module ti.sysbios.BIOS

SYS/BIOS Master Manager

This module is responsible for setting up global parameters pertaining to SYS/BIOS and for performing the SYS/BIOS startup sequence. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/BIOS.xdc
#include <ti/sysbios/BIOS.h>
Functions
Void 
Void 
Void 
Void 
Functions common to all target modules
Defines
#define
#define
Typedefs
typedef enum
typedef Void 
typedef enum
Constants
extern const Bool 
extern const Types_FreqHz 
extern const String 
extern const SizeT 
extern const Bool 
extern const Bool 
 
DETAILS
This module is responsible for setting up global parameters pertaining to SYS/BIOS and for performing the SYS/BIOS startup sequence.
BIOS configures the Memory.defaultHeapInstance using a HeapMem instance of size BIOS.heapSize.
The SYS/BIOS startup sequence is logically divided into two phases: those operations that occur prior to the application's "main()" function being called, and those operations that are performed after the application's "main()" function is invoked.
The "before main()" startup sequence is governed completely by the RTSC runtime package.
The "after main()" startup sequence is governed by SYS/BIOS and is initiated by an explicit call to the BIOS_start() function at the end of the application's main() function.
Control points are provided at various places in each of the two startup sequences for user startup operations to be inserted.
The RTSC runtime startup sequence is as follows:
  1. Immediately after CPU reset, perform target-specific CPU initialization (beginning at c_int00).
  2. Prior to cinit(), run the single user-supplied "reset function" (see Startup.resetFxn).
  3. Run cinit() to initialize C runtime environment.
  4. Run the user-supplied "first functions" (see Startup.firstFxns).
  5. Run all the module initialization functions.
  6. Run pinit().
  7. Run the user-supplied "last functions" (see Startup.lastFxns).
  8. Run main().
The SYS/BIOS startup sequence begins at the end of main() when BIOS_start() is called:
  1. Run the user-supplied "startup functions" (see BIOS.startupFxns).
  2. Enable Hardware Interrupts.
  3. Enable Software Interrupts. If the system supports Software Interrupts (Swis) (see BIOS.swiEnabled), then the SYS/BIOS startup sequence enables Swis at this point.
  4. Timer Startup. If the system supports Timers, then at this point all statically configured timers are initialized per their user-configuration. If a timer was configured to start "automatically", it is started here.
  5. Task Startup. If the system supports Tasks (see BIOS.taskEnabled), then task scheduling begins here. If there are no statically or dynamically created Tasks in the system, then execution proceeds directly to the Idle loop.
Below is a configuration script excerpt that installs a user-supplied startup function at every possible control point in the RTSC and SYS/BIOS startup sequence:
  // get handle to xdc Startup module
  var Startup = xdc.useModule('xdc.runtime.Startup');
  
  // install "reset function"
  Startup.resetFxn = '&myReset';
  
  // install a "first function"
  var len = Startup.firstFxns.length
  Startup.firstFxns.length++;
  Startup.firstFxns[len] = '&myFirst';
  
  // install a "last function"
  var len = Startup.lastFxns.length
  Startup.lastFxns.length++;
  Startup.lastFxns[len] = '&myLast';
  
  // get handle to BIOS module
  var BIOS = xdc.useModule('ti.sysbios.BIOS');
  
  // install a SYS/BIOS startup function
  BIOS.addUserStartupFunction('&myBiosStartup');

Calling Context

Function Hwi Swi Task Main Startup
getCpuFreq Y Y Y Y Y
getThreadType Y Y Y Y N
setCpuFreq Y Y Y Y Y
start N N N Y N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. BIOS_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. BIOS_Module_startupDone() returns FALSE).
const BIOS_NO_WAIT

Used in APIs that take a timeout to specify no waiting

C synopsis target-domain
#define BIOS_NO_WAIT (UInt)0
const BIOS_WAIT_FOREVER

Used in APIs that take a timeout to specify wait forever

C synopsis target-domain
#define BIOS_WAIT_FOREVER (UInt)~(0)
enum BIOS_RtsLockType

type of Gate to use in the TI RTS library

C synopsis target-domain
typedef enum BIOS_RtsLockType {
    BIOS_NoLocking,
    BIOS_GateHwi,
    BIOS_GateSwi,
    BIOS_GateMutex,
    BIOS_GateMutexPri
} BIOS_RtsLockType;
enum BIOS_ThreadType

Current thread type definitions. Returned by getThreadType

C synopsis target-domain
typedef enum BIOS_ThreadType {
    BIOS_ThreadType_Hwi,
    // Current thread is a Hwi
    BIOS_ThreadType_Swi,
    // Current thread is a Swi
    BIOS_ThreadType_Task,
    // Current thread is a Task
    BIOS_ThreadType_Main
    // Current thread is Boot/Main
} BIOS_ThreadType;
typedef BIOS_StartupFuncPtr

User startup function type definition

C synopsis target-domain
typedef Void (*BIOS_StartupFuncPtr)(Void);
config BIOS_clockEnabled  // module-wide

SYS/BIOS Clock services enable flag. Default is true

C synopsis target-domain
extern const Bool BIOS_clockEnabled;
DETAILS
The following behaviors occur when clockEnabled is set to false:
config BIOS_cpuFreq  // module-wide

CPU frequency in Hz

C synopsis target-domain
extern const Types_FreqHz BIOS_cpuFreq;
DETAILS
Example: If CPU frequency is 720MHz, do the following in configuration script. var BIOS = xdc.useModule('ti.sysbios.BIOS'); BIOS.cpuFreq.hi = 0; BIOS.cpuFreq.lo = 720000000;
config BIOS_heapSection  // module-wide

Section to place the system heap

C synopsis target-domain
extern const String BIOS_heapSection;
DETAILS
Default is null which means heap gets placed in default data section.
config BIOS_heapSize  // module-wide

Size of system heap

C synopsis target-domain
extern const SizeT BIOS_heapSize;
DETAILS
If the application configuration does not set Memory.defaultHeapInstance, then BIOS will create a HeapMem heap of this size. This heap will be assigned to Memory.defaultHeapInstance and will therefore be used as the default system heap. This heap will also be used by the BIOS version of the RTS malloc/calloc/free() functions.
config BIOS_swiEnabled  // module-wide

SYS/BIOS Swi services enable flag. Default is true

C synopsis target-domain
extern const Bool BIOS_swiEnabled;
DETAILS
The following behaviors occur when swiEnabled is set to false:
  • Static Swi creation will result in a fatal build error.
  • The Clock module is effectively disabled as it uses a Swi to process the Clock objects.
  • See other effects as noted for clockEnabled = false;
  • Runtime Swi create will assert.
config BIOS_taskEnabled  // module-wide

SYS/BIOS Task services enable flag. Default is true

C synopsis target-domain
extern const Bool BIOS_taskEnabled;
DETAILS
The following behaviors occur when taskEnabled is set to false:
  • Static Task creation will result in a fatal build error.
  • The Idle task object is not created. (The Idle functions are invoked within the start() thread.)
  • Runtime Task create will assert.
BIOS_exit()  // module-wide

Exit currently running SYS/BIOS executable

C synopsis target-domain
Void BIOS_exit(Int stat);
ARGUMENTS
stat — exit status to return to calling environment.
DETAILS
This function is called when a SYS/BIOS executable needs to terminate normally. This function sets the internal SYS/BIOS threadType to ThreadType_Main and then calls System_exit(stat), passing along the 'stat' argument.
All functions bound via System_atexit or the ANSI C Standard Library atexit function are then executed. The System.SupportProxy's exit function is called during this time.
BIOS_getCpuFreq()  // module-wide

Get CPU frequency in Hz

C synopsis target-domain
Void BIOS_getCpuFreq(Types_FreqHz *freq);
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_getThreadType()  // module-wide

Get the current thread type

C synopsis target-domain
BIOS_ThreadType BIOS_getThreadType();
RETURNS
Current thread type
BIOS_setCpuFreq()  // module-wide

Set CPU Frequency in Hz

C synopsis target-domain
Void BIOS_setCpuFreq(Types_FreqHz *freq);
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_start()  // module-wide

Start bios

C synopsis target-domain
Void BIOS_start();
DETAILS
The user's main() function is required to call this function after all other user initializations have been performed.
This function does not return.
This function performs any remaining SYS/BIOS initializations and then transfers control to the highest priority ready task if taskEnabled is true. If taskEnabled is false, control is transferred directly to the Idle Loop.
The SYS/BIOS start sequence is as follows:
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId BIOS_Module_id();
// Get this module's unique id
 
Bool BIOS_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle BIOS_Module_heap();
// The heap from which this module allocates memory
 
Bool BIOS_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 BIOS_Module_getMask();
// Returns the diagnostics mask for this module
 
Void BIOS_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/sysbios/BIOS.xdc
var BIOS = xdc.useModule('ti.sysbios.BIOS');
module-wide constants & types
        const BIOS.NoLocking;
        const BIOS.GateHwi;
        const BIOS.GateSwi;
        const BIOS.GateMutex;
        const BIOS.GateMutexPri;
    var obj = new BIOS.ModuleView// ;
        obj.currentThreadType = String  ...
        obj.rtsGateType = String  ...
        obj.cpuFreqLow = Int  ...
        obj.cpuFreqHigh = Int  ...
        obj.clockEnabled = Bool  ...
        obj.swiEnabled = Bool  ...
        obj.taskEnabled = Bool  ...
        obj.startFunc = String  ...
module-wide config parameters
    BIOS.heapSize// Size of system heap = SizeT 0x1000;
 
const BIOS.NO_WAIT

Used in APIs that take a timeout to specify no waiting

XDCscript usage meta-domain
const BIOS.NO_WAIT = 0;
C SYNOPSIS
const BIOS.WAIT_FOREVER

Used in APIs that take a timeout to specify wait forever

XDCscript usage meta-domain
const BIOS.WAIT_FOREVER = ~(0);
C SYNOPSIS
enum BIOS.RtsLockType

type of Gate to use in the TI RTS library

XDCscript usage meta-domain
values of type BIOS.RtsLockType
    const BIOS.NoLocking;
    const BIOS.GateHwi;
    const BIOS.GateSwi;
    const BIOS.GateMutex;
    const BIOS.GateMutexPri;
C SYNOPSIS
enum BIOS.ThreadType

Current thread type definitions. Returned by getThreadType

XDCscript usage meta-domain
values of type BIOS.ThreadType
    const BIOS.ThreadType_Hwi;
    // Current thread is a Hwi
    const BIOS.ThreadType_Swi;
    // Current thread is a Swi
    const BIOS.ThreadType_Task;
    // Current thread is a Task
    const BIOS.ThreadType_Main;
    // Current thread is Boot/Main
C SYNOPSIS
metaonly struct BIOS.ModuleView
XDCscript usage meta-domain
var obj = new BIOS.ModuleView;
 
    obj.currentThreadType = String  ...
    obj.rtsGateType = String  ...
    obj.cpuFreqLow = Int  ...
    obj.cpuFreqHigh = Int  ...
    obj.clockEnabled = Bool  ...
    obj.swiEnabled = Bool  ...
    obj.taskEnabled = Bool  ...
    obj.startFunc = String  ...
config BIOS.clockEnabled  // module-wide

SYS/BIOS Clock services enable flag. Default is true

XDCscript usage meta-domain
BIOS.clockEnabled = Bool true;
DETAILS
The following behaviors occur when clockEnabled is set to false:
C SYNOPSIS
config BIOS.cpuFreq  // module-wide

CPU frequency in Hz

XDCscript usage meta-domain
BIOS.cpuFreq = Types.FreqHz undefined;
DETAILS
Example: If CPU frequency is 720MHz, do the following in configuration script. var BIOS = xdc.useModule('ti.sysbios.BIOS'); BIOS.cpuFreq.hi = 0; BIOS.cpuFreq.lo = 720000000;
C SYNOPSIS
config BIOS.heapSection  // module-wide

Section to place the system heap

XDCscript usage meta-domain
BIOS.heapSection = String null;
DETAILS
Default is null which means heap gets placed in default data section.
C SYNOPSIS
config BIOS.heapSize  // module-wide

Size of system heap

XDCscript usage meta-domain
BIOS.heapSize = SizeT 0x1000;
DETAILS
If the application configuration does not set Memory.defaultHeapInstance, then BIOS will create a HeapMem heap of this size. This heap will be assigned to Memory.defaultHeapInstance and will therefore be used as the default system heap. This heap will also be used by the BIOS version of the RTS malloc/calloc/free() functions.
C SYNOPSIS
config BIOS.swiEnabled  // module-wide

SYS/BIOS Swi services enable flag. Default is true

XDCscript usage meta-domain
BIOS.swiEnabled = Bool true;
DETAILS
The following behaviors occur when swiEnabled is set to false:
  • Static Swi creation will result in a fatal build error.
  • The Clock module is effectively disabled as it uses a Swi to process the Clock objects.
  • See other effects as noted for clockEnabled = false;
  • Runtime Swi create will assert.
C SYNOPSIS
config BIOS.taskEnabled  // module-wide

SYS/BIOS Task services enable flag. Default is true

XDCscript usage meta-domain
BIOS.taskEnabled = Bool true;
DETAILS
The following behaviors occur when taskEnabled is set to false:
  • Static Task creation will result in a fatal build error.
  • The Idle task object is not created. (The Idle functions are invoked within the start() thread.)
  • Runtime Task create will assert.
C SYNOPSIS
metaonly config BIOS.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
BIOS.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config BIOS.rovViewInfo  // module-wide
XDCscript usage meta-domain
BIOS.rovViewInfo = ViewInfo.Instance ViewInfo.create;
metaonly config BIOS.rtsGateType  // module-wide

Gate to make sure TI RTS library APIs are re-entrant

XDCscript usage meta-domain
BIOS.rtsGateType = BIOS.RtsLockType undefined;
DETAILS
The application gets to determine the type of gate (lock) that is used in the TI RTS library. The gate will be used to guarantee re-entrancy of the RTS APIs.
The type of gate depends on the type of threads that are going to be calling into the RTS library. For example, if both Swi and Task threads are going to be calling the RTS library's printf, GateSwi should be used. Then Hwi threads are not impacted (i.e. disabled) during the printf calls from the Swi or Task threads.
If NoLocking is used, the RTS lock is not plugged and re-entrancy for the TI RTS library calls are not guaranteed. The application can plug the RTS locks directly if it wants.
Gate Type
GateHwi: Interrupts are disabled and restored to maintain re-entrancy in RTS. Use if only making RTS calls from a Hwi, Swi and/or Task.
GateSwi: Swis are disabled and restored to maintain re-entrancy in RTS Use if only making RTS calls from a Swi and/or Task.
GateMutex: A single mutex is used to maintain re-entrancy in RTS. Use if only making RTS calls from a Task. Blocks only Tasks that are also trying to execute critical regions of RTS library.
GateMutexPri: A priority inheriting mutex is used to maintain re-entrancy in RTS. Use if only making RTS calls from a Task. Blocks only Tasks that are also trying to execute critical regions of RTS library. Raises the priority of the Task that is executing the critical region in the RTS library to the level of the higher priority Task that is trying to execute a critical region of the RTS library also.
The default is to use depends on the type of threading model. If taskEnabled is true, GateMutex is used. If swiEnabled is true and taskEnabled is false: GateSwi is used. If both swiEnabled and taskEnabled are false: xdc.runtime.GateNull is used.
If taskEnabled is false, the user should not select GateMutex (or other Task level gates). Similarly, if taskEnabled and swiEnabledare false, the user should not select GateSwi or the Task level gates.
metaonly config BIOS.startupFxns  // module-wide

The array of user (and middleware) provided functions to be executed at the beginning of BIOS_start()

XDCscript usage meta-domain
BIOS.startupFxns = BIOS.StartupFuncPtr[] [ ];
DETAILS
These functions are executed before Hwis, Swis, and Tasks are started.
generated on Thu, 03 Feb 2011 19:01:31 GMT