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 ... ]
#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 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:
- Immediately after CPU reset, perform target-specific CPU
initialization (beginning at c_int00).
- Prior to cinit(), run the single user-supplied "reset function"
(see Startup.resetFxn).
- Run cinit() to initialize C runtime environment.
- Run the user-supplied "first functions"
(see Startup.firstFxns).
- Run all the module initialization functions.
- Run pinit().
- Run the user-supplied "last functions"
(see Startup.lastFxns).
- Run main().
The SYS/BIOS startup sequence begins at the end of main() when BIOS_start()
is called:
- Run the user-supplied "startup functions"
(see BIOS.startupFxns).
- Enable Hardware Interrupts.
- Enable Software Interrupts. If the system supports Software Interrupts
(Swis) (see BIOS.swiEnabled), then the SYS/BIOS
startup sequence enables Swis at this point.
- 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.
- 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
#define BIOS_NO_WAIT (UInt)0
const BIOS_WAIT_FOREVER |
|
Used in APIs that take a timeout to specify wait forever
#define BIOS_WAIT_FOREVER (UInt)~(0)
enum BIOS_RtsLockType |
|
type of Gate to use in the TI RTS library
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
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
typedef Void (*BIOS_StartupFuncPtr)(Void);
config BIOS_clockEnabled // module-wide |
|
SYS/BIOS Clock services enable flag. Default is true
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
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
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
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
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
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
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
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_getThreadType() // module-wide |
|
Get the current thread type
RETURNS
Current thread type
BIOS_setCpuFreq() // module-wide |
|
Set CPU Frequency in Hz
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_start() // module-wide |
|
Start bios
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 |
|
// Get this module's unique id
Bool BIOS_Module_startupDone();
// Test if this module has completed startup
// 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
var BIOS = xdc.useModule('ti.sysbios.BIOS');
module-wide constants & types
module-wide config parameters
const BIOS.NO_WAIT |
|
Used in APIs that take a timeout to specify no waiting
XDCscript usage |
meta-domain |
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 |
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 |
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 |
metaonly config BIOS.rtsGateType // module-wide |
|
Gate to make sure TI RTS library APIs are re-entrant
XDCscript usage |
meta-domain |
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 |
DETAILS
These functions are executed before Hwis, Swis, and Tasks are
started.
generated on Thu, 03 Feb 2011 19:01:31 GMT