module ti.sysbios.BIOS
index URL

BIOS Master Manager

Responsible for setting up global parameters pertaining to DSP/BIOS. [ more ... ]
XDCspec summary sourced in ti/sysbios/BIOS.xdc
module BIOS {  ...
// inherits xdc.runtime.IModule
C synopsis target-domain
#include <ti/sysbios/BIOS.h>
module-wide constants & types
    #define BIOS_NO_WAIT// Used in APIs that take a timeout to specify no waiting (UInt)0
    #define BIOS_WAIT_FOREVER// Used in APIs that take a timeout to specify wait forever (UInt)~(0)
 
    typedef enum BIOS_RtsLockType// type of Gate to use in the TI RTS library {
        BIOS_NoLocking,
        BIOS_GateHwi,
        BIOS_GateSwi,
        BIOS_GateMutex,
        BIOS_GateMutexPri
    } BIOS_RtsLockType;
 
    typedef enum BIOS_ThreadType// Current thread type definitions. Returned by getThreadType {
        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 Void (*BIOS_StartupFuncPtr// User startup function type definition)(Void);
module-wide config parameters
    extern const Bool BIOS_clockEnabled// BIOS Clock services enable flag. Default is true;
    extern const Types_FreqHz BIOS_cpuFreq// CPU frequency in Hz;
    extern const Bool BIOS_swiEnabled// BIOS Swi services enable flag. Default is true;
    extern const Bool BIOS_taskEnabled// BIOS Task services enable flag. Default is true;
module-wide functions
    Void BIOS_getCpuFreq// Get CPU frequency in Hz( Types_FreqHz *freq );
    BIOS_ThreadType BIOS_getThreadType// Get the current threadType( );
    Void BIOS_setCpuFreq// Set CPU Frequency in Hz( Types_FreqHz *freq );
    Void BIOS_start// Start bios( );
module-wide built-ins
    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// Set the diagnostics mask for this module( Bits16 mask );
 
XDCscript usage meta-domain
var BIOS = xdc.useModule('ti.sysbios.BIOS');
module-wide constants & types
    const BIOS.NO_WAIT// Used in APIs that take a timeout to specify no waiting = 0;
    const BIOS.WAIT_FOREVER// Used in APIs that take a timeout to specify wait forever = ~(0);
 
    values of type BIOS.RtsLockType// type of Gate to use in the TI RTS library
        const BIOS.NoLocking;
        const BIOS.GateHwi;
        const BIOS.GateSwi;
        const BIOS.GateMutex;
        const BIOS.GateMutexPri;
 
    values of type BIOS.ThreadType// Current thread type definitions. Returned by getThreadType
        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;
 
    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.clockEnabled// BIOS Clock services enable flag. Default is true = Bool true;
    BIOS.cpuFreq// CPU frequency in Hz = Types.FreqHz undefined;
    BIOS.swiEnabled// BIOS Swi services enable flag. Default is true = Bool true;
    BIOS.taskEnabled// BIOS Task services enable flag. Default is true = Bool true;
 
    BIOS.common$// Common module configuration parameters = Types.Common$ undefined;
    BIOS.rovViewInfo//  = ViewInfo.Instance ViewInfo.create;
    BIOS.rtsGateType// Gate to make sure TI RTS library APIs are re-entrant = BIOS.RtsLockType undefined;
    BIOS.startupFxns// The array of user (and middleware) provided functions to be executed at the beginning of BIOS_start() = BIOS.StartupFuncPtr[] [ ];
 
XDCspec declarations sourced in ti/sysbios/BIOS.xdc
package ti.sysbios;
 
module BIOS {
module-wide constants & types
    const UInt NO_WAIT// Used in APIs that take a timeout to specify no waiting = 0;
    const UInt WAIT_FOREVER// Used in APIs that take a timeout to specify wait forever = ~(0);
 
    enum RtsLockType// type of Gate to use in the TI RTS library {
        NoLocking,
        GateHwi,
        GateSwi,
        GateMutex,
        GateMutexPri
    };
 
    enum ThreadType// Current thread type definitions. Returned by getThreadType {
        ThreadType_Hwi// Current thread is a Hwi,
        ThreadType_Swi// Current thread is a Swi,
        ThreadType_Task// Current thread is a Task,
        ThreadType_Main// Current thread is Boot/Main
    };
 
    typedef Void (*StartupFuncPtr// User startup function type definition)(Void);
 
    metaonly struct ModuleView//  {
        String currentThreadType;
        String rtsGateType;
        Int cpuFreqLow;
        Int cpuFreqHigh;
        Bool clockEnabled;
        Bool swiEnabled;
        Bool taskEnabled;
        String startFunc;
    };
module-wide config parameters
    config Bool clockEnabled// BIOS Clock services enable flag. Default is true = true;
    config Types.FreqHz cpuFreq// CPU frequency in Hz;
    config Bool swiEnabled// BIOS Swi services enable flag. Default is true = true;
    config Bool taskEnabled// BIOS Task services enable flag. Default is true = true;
 
    metaonly config Types.Common$ common$// Common module configuration parameters;
    metaonly config ViewInfo.Instance rovViewInfo//  = ViewInfo.create;
    metaonly config BIOS.RtsLockType rtsGateType// Gate to make sure TI RTS library APIs are re-entrant;
    metaonly config BIOS.StartupFuncPtr startupFxns// The array of user (and middleware) provided functions to be executed at the beginning of BIOS_start()[] = [ ];
module-wide functions
    Void getCpuFreq// Get CPU frequency in Hz( Types.FreqHz *freq );
    BIOS.ThreadType getThreadType// Get the current threadType( );
    Void setCpuFreq// Set CPU Frequency in Hz( Types.FreqHz *freq );
    Void start// Start bios( );
}
DETAILS
Responsible for setting up global parameters pertaining to DSP/BIOS.
Responsible for BIOS startup.
The 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 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 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 DSP/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/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 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
index URL

Used in APIs that take a timeout to specify no waiting

XDCscript usage meta-domain
const BIOS.NO_WAIT = 0;
C synopsis target-domain
#define BIOS_NO_WAIT (UInt)0
 
 
const BIOS.WAIT_FOREVER
index URL

Used in APIs that take a timeout to specify wait forever

XDCscript usage meta-domain
const BIOS.WAIT_FOREVER = ~(0);
C synopsis target-domain
#define BIOS_WAIT_FOREVER (UInt)~(0)
 
 
enum BIOS.RtsLockType
index URL

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 target-domain
typedef enum BIOS_RtsLockType {
    BIOS_NoLocking,
    BIOS_GateHwi,
    BIOS_GateSwi,
    BIOS_GateMutex,
    BIOS_GateMutexPri
} BIOS_RtsLockType;
 
 
enum BIOS.ThreadType
index URL

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 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
index URL

User startup function type definition

C synopsis target-domain
typedef Void (*BIOS_StartupFuncPtr)(Void);
 
 
metaonly struct BIOS.ModuleView
index URL
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
index URL

BIOS Clock services enable flag. Default is true

XDCscript usage meta-domain
BIOS.clockEnabled = Bool 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
index URL

CPU frequency in Hz

XDCscript usage meta-domain
BIOS.cpuFreq = Types.FreqHz undefined;
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.swiEnabled  // module-wide
index URL

BIOS Swi services enable flag. Default is true

XDCscript usage meta-domain
BIOS.swiEnabled = Bool 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
index URL

BIOS Task services enable flag. Default is true

XDCscript usage meta-domain
BIOS.taskEnabled = Bool 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.
 
metaonly config BIOS.common$  // module-wide
index URL

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
index URL
XDCscript usage meta-domain
BIOS.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly config BIOS.rtsGateType  // module-wide
index URL

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-entracy 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: GateHwi is used.
If taskEnabled is false, the user should not select GateMutex (orother 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
index URL

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.
 
BIOS.getCpuFreq( )  // module-wide
index URL

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
index URL

Get the current threadType

C synopsis target-domain
BIOS_ThreadType BIOS_getThreadType( );
 
RETURNS
Previous threadType
 
BIOS.setCpuFreq( )  // module-wide
index URL

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
index URL

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 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 BIOS start sequence is as follows:
 
module-wide built-ins
index URL

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
generated on Mon, 21 Dec 2009 19:43:39 GMT